agentwheel 0.16.6 → 0.17.0

package/dist/index.js

@@ -3,17 +3,19 @@ import {
   atomicCopy,
   hashPath,
   inferSourceDriverName,
+  isAlreadyExists,
   isIgnoredGeneratedEntry,
   pathExists,
+  withFilesystemLock,
   writeJsonAtomic
-} from "./chunk-PKAPR55N.js";
+} from "./chunk-24IUHC3D.js";
 
 // src/cli/index.ts
-import { createHash as createHash14 } from "crypto";
+import { createHash as createHash15 } from "crypto";
 import { existsSync } from "fs";
-import { mkdir as mkdir23, rm as rm12, writeFile as writeFile22 } from "fs/promises";
+import { mkdir as mkdir24, rm as rm13, writeFile as writeFile22 } from "fs/promises";
 import { homedir as homedir12 } from "os";
-import { dirname as dirname32, join as join48, resolve as resolve22 } from "path";
+import { dirname as dirname33, join as join49, resolve as resolve22 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command } from "commander";
 
@@ -495,113 +497,126 @@ import { promisify as promisify3 } from "util";
 import { createHash } from "crypto";
 import { mkdir, readFile as readFile3, rename, writeFile as writeFile2 } from "fs/promises";
 import { dirname } from "path";
+import { z as z4 } from "zod";
+
+// src/model/cache-identity.ts
 import { z as z3 } from "zod";
-var graphLockNodeSchema = z3.object({
-  id: z3.string().min(1),
-  name: z3.string().min(1),
-  version: z3.string().min(1),
-  source: z3.string().min(1),
-  normalizedSource: z3.string().min(1),
-  driver: z3.string().min(1),
-  requestedRef: z3.string().min(1).optional(),
-  resolvedCommit: z3.string().min(1).optional(),
-  sourceHash: z3.string().min(16),
-  mode: z3.enum(["pinned", "tracking"]),
-  requiredBy: z3.array(z3.string().min(1)),
-  selected: z3.array(z3.string().min(1)),
-  selectionReasons: z3.record(z3.string(), z3.array(z3.string().min(1))).optional()
+var immutableCacheIdentitySchema = z3.string().regex(
+  /^(?:[0-9a-f]{40}|content-[0-9a-f]{64})$/i,
+  "Expected a Git commit or content-addressed SHA-256 cache identity"
+);
+function normalizeImmutableCacheIdentity(value) {
+  return value === void 0 ? void 0 : immutableCacheIdentitySchema.parse(value).toLowerCase();
+}
+
+// src/model/graph-lock.ts
+var graphLockNodeSchema = z4.object({
+  id: z4.string().min(1),
+  name: z4.string().min(1),
+  version: z4.string().min(1),
+  source: z4.string().min(1),
+  normalizedSource: z4.string().min(1),
+  driver: z4.string().min(1),
+  requestedRef: z4.string().min(1).optional(),
+  resolvedCommit: z4.string().min(1).optional(),
+  cacheIdentity: immutableCacheIdentitySchema.optional(),
+  sourceHash: z4.string().min(16),
+  mode: z4.enum(["pinned", "tracking"]),
+  requiredBy: z4.array(z4.string().min(1)),
+  selected: z4.array(z4.string().min(1)),
+  selectionReasons: z4.record(z4.string(), z4.array(z4.string().min(1))).optional()
 });
-var graphLockRootSchema = z3.object({
-  rootId: z3.string().min(1),
-  source: z3.string().min(1),
-  normalizedSource: z3.string().min(1),
-  graphNodeId: z3.string().min(1),
-  mode: z3.enum(["pinned", "tracking"]),
-  selected: z3.array(z3.string().min(1)),
-  aliases: z3.record(z3.string(), z3.string().min(1)).optional(),
-  overrides: z3.array(z3.string().min(1)).optional(),
-  selectionImport: z3.object({
-    configPath: z3.string().min(1),
-    configHash: z3.string().min(16),
-    exportHash: z3.string().min(16),
-    exportName: z3.string().min(1),
-    extends: z3.array(z3.string().min(1)),
-    inherited: z3.array(z3.string().min(1)),
-    additions: z3.array(z3.string().min(1)),
-    exclusions: z3.array(z3.string().min(1)),
-    effective: z3.array(z3.string().min(1))
+var graphLockRootSchema = z4.object({
+  rootId: z4.string().min(1),
+  source: z4.string().min(1),
+  normalizedSource: z4.string().min(1),
+  graphNodeId: z4.string().min(1),
+  mode: z4.enum(["pinned", "tracking"]),
+  selected: z4.array(z4.string().min(1)),
+  aliases: z4.record(z4.string(), z4.string().min(1)).optional(),
+  overrides: z4.array(z4.string().min(1)).optional(),
+  selectionImport: z4.object({
+    configPath: z4.string().min(1),
+    configHash: z4.string().min(16),
+    exportHash: z4.string().min(16),
+    exportName: z4.string().min(1),
+    extends: z4.array(z4.string().min(1)),
+    inherited: z4.array(z4.string().min(1)),
+    additions: z4.array(z4.string().min(1)),
+    exclusions: z4.array(z4.string().min(1)),
+    effective: z4.array(z4.string().min(1))
   }).optional()
 });
-var graphLockEdgeSchema = z3.object({
-  from: z3.string().min(1),
-  to: z3.string().min(1),
-  alias: z3.string().min(1),
-  source: z3.string().min(1),
-  normalizedSource: z3.string().min(1),
-  requestedRef: z3.string().min(1).optional(),
-  version: z3.string().min(1).optional(),
-  mode: z3.enum(["pinned", "tracking"]),
-  optional: z3.boolean().default(false),
-  selected: z3.array(z3.string().min(1))
+var graphLockEdgeSchema = z4.object({
+  from: z4.string().min(1),
+  to: z4.string().min(1),
+  alias: z4.string().min(1),
+  source: z4.string().min(1),
+  normalizedSource: z4.string().min(1),
+  requestedRef: z4.string().min(1).optional(),
+  version: z4.string().min(1).optional(),
+  mode: z4.enum(["pinned", "tracking"]),
+  optional: z4.boolean().default(false),
+  selected: z4.array(z4.string().min(1))
 });
-var graphLockIncludeEdgeSchema = z3.object({
-  fromNodeId: z3.string().min(1),
-  alias: z3.string().min(1),
-  toNodeId: z3.string().min(1),
-  selector: z3.string().min(1),
-  sourceHash: z3.string().min(16)
+var graphLockIncludeEdgeSchema = z4.object({
+  fromNodeId: z4.string().min(1),
+  alias: z4.string().min(1),
+  toNodeId: z4.string().min(1),
+  selector: z4.string().min(1),
+  sourceHash: z4.string().min(16)
 });
-var graphLockArtifactSchema = z3.object({
-  graphNodeId: z3.string().min(1),
-  dependencyRole: z3.enum(["root", "direct", "transitive", "fragment"]),
+var graphLockArtifactSchema = z4.object({
+  graphNodeId: z4.string().min(1),
+  dependencyRole: z4.enum(["root", "direct", "transitive", "fragment"]),
   type: artifactTypeSchema,
-  name: z3.string().min(1),
-  installName: z3.string().min(1),
-  logicalSelector: z3.string().min(1),
-  owners: z3.array(z3.string().min(1)),
-  relativePath: z3.string().min(1),
+  name: z4.string().min(1),
+  installName: z4.string().min(1),
+  logicalSelector: z4.string().min(1),
+  owners: z4.array(z4.string().min(1)),
+  relativePath: z4.string().min(1),
   kind: fileKindSchema,
-  hash: z3.string().min(16),
-  channel: z3.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed"),
-  composedFrom: z3.array(composedFromEntrySchema).optional()
+  hash: z4.string().min(16),
+  channel: z4.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed"),
+  composedFrom: z4.array(composedFromEntrySchema).optional()
 });
-var graphLockPlainNameIncumbentSchema = z3.object({
-  adapter: z3.string().min(1),
-  targetFingerprint: z3.string().min(1),
+var graphLockPlainNameIncumbentSchema = z4.object({
+  adapter: z4.string().min(1),
+  targetFingerprint: z4.string().min(1),
   type: artifactTypeSchema,
-  name: z3.string().min(1),
-  graphNodeId: z3.string().min(1)
+  name: z4.string().min(1),
+  graphNodeId: z4.string().min(1)
 });
-var graphLockNamespacingSchema = z3.object({
-  graphNodeId: z3.string().min(1),
+var graphLockNamespacingSchema = z4.object({
+  graphNodeId: z4.string().min(1),
   type: artifactTypeSchema,
-  name: z3.string().min(1),
-  installName: z3.string().min(1),
-  reason: z3.enum(["alias", "transitive-collision"])
+  name: z4.string().min(1),
+  installName: z4.string().min(1),
+  reason: z4.enum(["alias", "transitive-collision"])
 });
-var graphLockOverrideSchema = z3.object({
-  rootId: z3.string().min(1),
-  selector: z3.string().min(1),
-  graphNodeId: z3.string().min(1),
-  overriddenGraphNodeId: z3.string().min(1),
+var graphLockOverrideSchema = z4.object({
+  rootId: z4.string().min(1),
+  selector: z4.string().min(1),
+  graphNodeId: z4.string().min(1),
+  overriddenGraphNodeId: z4.string().min(1),
   type: artifactTypeSchema,
-  name: z3.string().min(1),
-  installName: z3.string().min(1)
+  name: z4.string().min(1),
+  installName: z4.string().min(1)
 });
-var graphLockCanonicalSchema = z3.object({
-  targetFingerprint: z3.string().min(1).optional(),
-  roots: z3.array(graphLockRootSchema),
-  nodes: z3.array(graphLockNodeSchema),
-  edges: z3.array(graphLockEdgeSchema),
-  includeEdges: z3.array(graphLockIncludeEdgeSchema).default([]),
-  artifacts: z3.array(graphLockArtifactSchema).default([]),
-  namespacing: z3.array(graphLockNamespacingSchema).default([]),
-  overrides: z3.array(graphLockOverrideSchema).default([]),
-  plainNameIncumbents: z3.array(graphLockPlainNameIncumbentSchema).default([])
+var graphLockCanonicalSchema = z4.object({
+  targetFingerprint: z4.string().min(1).optional(),
+  roots: z4.array(graphLockRootSchema),
+  nodes: z4.array(graphLockNodeSchema),
+  edges: z4.array(graphLockEdgeSchema),
+  includeEdges: z4.array(graphLockIncludeEdgeSchema).default([]),
+  artifacts: z4.array(graphLockArtifactSchema).default([]),
+  namespacing: z4.array(graphLockNamespacingSchema).default([]),
+  overrides: z4.array(graphLockOverrideSchema).default([]),
+  plainNameIncumbents: z4.array(graphLockPlainNameIncumbentSchema).default([])
 });
-var graphLockSchema = z3.object({
-  version: z3.literal(1),
-  generatedAt: z3.string().datetime().optional(),
+var graphLockSchema = z4.object({
+  version: z4.literal(1),
+  generatedAt: z4.string().datetime().optional(),
   canonical: graphLockCanonicalSchema
 });
 async function readGraphLock(path) {
@@ -1052,56 +1067,56 @@ import { createHash as createHash2 } from "crypto";
 import { resolve as resolve3 } from "path";
 
 // src/model/manifest.ts
-import { z as z4 } from "zod";
-var mergeValueSchema = z4.lazy(() => z4.union([
-  z4.null(),
-  z4.boolean(),
-  z4.number(),
-  z4.string(),
-  z4.array(mergeValueSchema),
-  z4.record(z4.string(), mergeValueSchema)
+import { z as z5 } from "zod";
+var mergeValueSchema = z5.lazy(() => z5.union([
+  z5.null(),
+  z5.boolean(),
+  z5.number(),
+  z5.string(),
+  z5.array(mergeValueSchema),
+  z5.record(z5.string(), mergeValueSchema)
 ]));
-var mergeRemovalSchema = z4.record(z4.string(), mergeValueSchema);
-var dependencyRoleSchema = z4.enum(["root", "direct", "transitive", "fragment"]);
+var mergeRemovalSchema = z5.record(z5.string(), mergeValueSchema);
+var dependencyRoleSchema = z5.enum(["root", "direct", "transitive", "fragment"]);
 var legacyUnownedWorkspaceOwner = "legacy:unowned";
-var semanticPluginSpecSchema = z4.object({
-  runtime: z4.enum(["openclaw", "claude", "codex", "copilot", "hermes"]),
-  pluginName: z4.string().min(1),
-  marketplaceName: z4.string().min(1).optional(),
-  stateRoot: z4.string().min(1).optional(),
-  installCommands: z4.array(z4.array(z4.string()).min(1)).min(1),
-  uninstallCommands: z4.array(z4.array(z4.string()).min(1)).min(1),
-  enableCommands: z4.array(z4.array(z4.string()).min(1)).optional(),
-  disableCommands: z4.array(z4.array(z4.string()).min(1)).optional()
+var semanticPluginSpecSchema = z5.object({
+  runtime: z5.enum(["openclaw", "claude", "codex", "copilot", "hermes"]),
+  pluginName: z5.string().min(1),
+  marketplaceName: z5.string().min(1).optional(),
+  stateRoot: z5.string().min(1).optional(),
+  installCommands: z5.array(z5.array(z5.string()).min(1)).min(1),
+  uninstallCommands: z5.array(z5.array(z5.string()).min(1)).min(1),
+  enableCommands: z5.array(z5.array(z5.string()).min(1)).optional(),
+  disableCommands: z5.array(z5.array(z5.string()).min(1)).optional()
 });
-var manifestEntryV1Schema = z4.object({
-  path: z4.string().min(1),
+var manifestEntryV1Schema = z5.object({
+  path: z5.string().min(1),
   artifactType: artifactTypeSchema,
-  artifactName: z4.string().min(1),
+  artifactName: z5.string().min(1),
   kind: fileKindSchema,
-  hash: z4.string().min(16),
-  sourceHash: z4.string().min(16),
-  updatedAt: z4.string().datetime(),
-  channel: z4.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed"),
-  packageName: z4.string().min(1).optional(),
-  semanticCommand: z4.array(z4.string()).optional(),
+  hash: z5.string().min(16),
+  sourceHash: z5.string().min(16),
+  updatedAt: z5.string().datetime(),
+  channel: z5.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed"),
+  packageName: z5.string().min(1).optional(),
+  semanticCommand: z5.array(z5.string()).optional(),
   semanticPlugin: semanticPluginSpecSchema.optional(),
-  executed: z4.boolean().optional(),
-  mergeStrategy: z4.enum(["json-deep", "openclaw-json-deep", "yaml-deep", "codex-toml-mcp"]).optional(),
+  executed: z5.boolean().optional(),
+  mergeStrategy: z5.enum(["json-deep", "openclaw-json-deep", "yaml-deep", "codex-toml-mcp"]).optional(),
   mergeRemoval: mergeRemovalSchema.optional(),
-  mergeCreatedDestination: z4.boolean().optional(),
-  mode: z4.enum(["managed-block"]).optional(),
-  composedFrom: z4.array(composedFromEntrySchema).optional()
+  mergeCreatedDestination: z5.boolean().optional(),
+  mode: z5.enum(["managed-block"]).optional(),
+  composedFrom: z5.array(composedFromEntrySchema).optional()
 });
 var manifestEntrySchema = manifestEntryV1Schema.extend({
-  installName: z4.string().min(1),
-  logicalSelector: z4.string().min(1).optional(),
-  graphNodeId: z4.string().min(1).optional(),
+  installName: z5.string().min(1),
+  logicalSelector: z5.string().min(1).optional(),
+  graphNodeId: z5.string().min(1).optional(),
   dependencyRole: dependencyRoleSchema.default("root"),
-  owners: z4.array(z4.string().min(1)).min(1),
-  refCount: z4.number().int().positive(),
-  workspaceOwner: z4.string().min(1).default(legacyUnownedWorkspaceOwner),
-  graphLockDigest: z4.string().min(1).optional()
+  owners: z5.array(z5.string().min(1)).min(1),
+  refCount: z5.number().int().positive(),
+  workspaceOwner: z5.string().min(1).default(legacyUnownedWorkspaceOwner),
+  graphLockDigest: z5.string().min(1).optional()
 }).transform((entry) => {
   const owners = [...new Set(entry.owners)].sort();
   return {
@@ -1110,59 +1125,60 @@ var manifestEntrySchema = manifestEntryV1Schema.extend({
     refCount: owners.length
   };
 });
-var installManifestV1Schema = z4.object({
-  version: z4.literal(1),
-  adapter: z4.string().min(1),
-  targetRoot: z4.string().min(1),
-  generatedAt: z4.string().datetime(),
-  adapterCode: z4.object({
-    modulePath: z4.string().min(1),
-    hash: z4.string().min(16)
+var installManifestV1Schema = z5.object({
+  version: z5.literal(1),
+  adapter: z5.string().min(1),
+  targetRoot: z5.string().min(1),
+  generatedAt: z5.string().datetime(),
+  adapterCode: z5.object({
+    modulePath: z5.string().min(1),
+    hash: z5.string().min(16)
   }).optional(),
-  entries: z4.array(manifestEntryV1Schema)
+  entries: z5.array(manifestEntryV1Schema)
 }).transform((manifest) => ({
   ...manifest,
   legacy: true
 }));
-var installManifestV2Schema = z4.object({
-  version: z4.literal(2),
-  adapter: z4.string().min(1),
+var installManifestV2Schema = z5.object({
+  version: z5.literal(2),
+  adapter: z5.string().min(1),
   installationType: installationTypeSchema.default(defaultInstallationType),
-  stateKey: z4.string().min(1).optional(),
-  targetRoot: z4.string().min(1),
-  generatedAt: z4.string().datetime(),
-  revision: z4.string().min(16),
-  adapterCode: z4.object({
-    modulePath: z4.string().min(1),
-    hash: z4.string().min(16)
+  stateKey: z5.string().min(1).optional(),
+  targetRoot: z5.string().min(1),
+  generatedAt: z5.string().datetime(),
+  revision: z5.string().min(16),
+  adapterCode: z5.object({
+    modulePath: z5.string().min(1),
+    hash: z5.string().min(16)
   }).optional(),
-  entries: z4.array(manifestEntrySchema)
+  entries: z5.array(manifestEntrySchema)
 }).transform((manifest) => ({
   ...manifest,
   legacy: false
 }));
-var installManifestSchema = z4.union([installManifestV2Schema, installManifestV1Schema]);
-var sourceLockSchema = z4.object({
-  version: z4.literal(1),
-  driver: z4.string().min(1),
-  source: z4.string().min(1),
-  resolvedPath: z4.string().min(1),
-  packageName: z4.string().min(1).optional(),
-  packageVersion: z4.string().min(1).optional(),
-  mode: z4.enum(["pinned", "tracking"]).default("pinned"),
-  requestedRef: z4.string().min(1).optional(),
-  resolvedCommit: z4.string().min(1).optional(),
-  sourceHash: z4.string().min(16).optional(),
-  generatedAt: z4.string().datetime(),
-  artifacts: z4.array(
-    z4.object({
+var installManifestSchema = z5.union([installManifestV2Schema, installManifestV1Schema]);
+var sourceLockSchema = z5.object({
+  version: z5.literal(1),
+  driver: z5.string().min(1),
+  source: z5.string().min(1),
+  resolvedPath: z5.string().min(1),
+  packageName: z5.string().min(1).optional(),
+  packageVersion: z5.string().min(1).optional(),
+  mode: z5.enum(["pinned", "tracking"]).default("pinned"),
+  requestedRef: z5.string().min(1).optional(),
+  resolvedCommit: z5.string().min(1).optional(),
+  cacheIdentity: immutableCacheIdentitySchema.optional(),
+  sourceHash: z5.string().min(16).optional(),
+  generatedAt: z5.string().datetime(),
+  artifacts: z5.array(
+    z5.object({
       type: artifactTypeSchema,
-      name: z4.string().min(1),
-      relativePath: z4.string().min(1),
+      name: z5.string().min(1),
+      relativePath: z5.string().min(1),
       kind: fileKindSchema,
-      hash: z4.string().min(16),
+      hash: z5.string().min(16),
       format: artifactFormatSchema.optional(),
-      composedFrom: z4.array(composedFromEntrySchema).optional()
+      composedFrom: z5.array(composedFromEntrySchema).optional()
     })
   )
 });
@@ -1307,7 +1323,7 @@ async function acquireApplyLock(targetRoot, adapter, transport = localTransport,
   try {
     await transport.mkdirExclusive(lockPath);
   } catch (error) {
-    if (!isAlreadyExists(error)) throw error;
+    if (!isAlreadyExists2(error)) throw error;
     await handleExistingLock(lockPath, ownerPath, transport, options);
     await transport.mkdirExclusive(lockPath);
   }
@@ -1405,7 +1421,7 @@ async function readLockOwner(ownerPath, transport) {
     return void 0;
   }
 }
-function isAlreadyExists(error) {
+function isAlreadyExists2(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
 }
 function journalTimestamp(date) {
@@ -1432,6 +1448,10 @@ async function mergeCodexTomlMcp(sourcePath, destPath) {
   await mkdir6(dirname7(destPath), { recursive: true });
   await writeFile6(destPath, merged, "utf8");
 }
+function mismatchedCodexTomlMcpServers(source, currentContent) {
+  const servers = extractMcpServers(source);
+  return Object.entries(servers).filter(([name, server]) => extractMcpServerBlock(currentContent, name) !== formatMcpServer(name, server)).map(([name]) => name);
+}
 function extractMcpServers(source) {
   const raw = isRecord2(source.mcpServers) ? source.mcpServers : source;
   const servers = {};
@@ -1483,6 +1503,32 @@ function formatMcpServer(name, server) {
   }
   return lines.join("\n");
 }
+function extractMcpServerBlock(content, serverName) {
+  const lines = content.split(/\r?\n/);
+  const blocks = [];
+  let block;
+  let collecting = false;
+  for (const line of lines) {
+    const section = line.match(/^\s*\[([^\]]+)]\s*$/)?.[1];
+    if (section) {
+      const match = section.match(/^mcp_servers\.([^\.\]]+)(?:\.|$)/);
+      const name = match?.[1] ? unquoteTomlKey(match[1]) : void 0;
+      if (collecting && block) {
+        while (block.at(-1)?.trim() === "") block.pop();
+        blocks.push(block);
+      }
+      collecting = name === serverName;
+      block = collecting ? [] : void 0;
+    }
+    if (collecting) block?.push(line);
+  }
+  if (collecting && block) {
+    while (block.at(-1)?.trim() === "") block.pop();
+    blocks.push(block);
+  }
+  if (blocks.length === 0) return void 0;
+  return blocks.map((lines2) => lines2.join("\n")).join("\n\n");
+}
 function formatTomlValue(value) {
   if (typeof value === "string") return JSON.stringify(value);
   if (typeof value === "number" || typeof value === "boolean") return String(value);
@@ -1571,9 +1617,53 @@ function dedupeArray2(values) {
 import { mkdir as mkdir8, readFile as readFile9, writeFile as writeFile8 } from "fs/promises";
 import { dirname as dirname9 } from "path";
 import { parse as parse3, stringify as stringify2 } from "yaml";
-async function mergeRemovalForInstall(sourcePath, strategy, currentContent) {
+var MergeAdoptionMismatchError = class extends Error {
+};
+function assertExactMcpMergeContribution(removal, strategy, currentContent) {
+  if (strategy === "codex-toml-mcp") {
+    const mismatched = mismatchedCodexTomlMcpServers(removal, currentContent);
+    if (mismatched.length > 0) {
+      throw new MergeAdoptionMismatchError(`exact MCP retirement precondition failed: Codex MCP server content differs or is missing for ${mismatched.join(", ")}`);
+    }
+    return;
+  }
+  if (strategy !== "json-deep") {
+    throw new MergeAdoptionMismatchError(`exact MCP retirement precondition failed: strategy ${strategy} is not supported`);
+  }
+  const mismatch = firstMcpContributionMismatch(parseMergeDestination(currentContent, strategy), removal);
+  if (mismatch) {
+    throw new MergeAdoptionMismatchError(`exact MCP retirement precondition failed: destination differs or is missing at ${mismatch}`);
+  }
+}
+function combineMergeRemovals(existing, incoming) {
+  return combineMergeValues(existing, incoming);
+}
+function hasMergeRemovalContent(removal) {
+  if (!removal) return false;
+  return Object.entries(removal).some(([key, value]) => {
+    return !(key === "mcpServers" && isRecord4(value) && Object.keys(value).length === 0);
+  });
+}
+async function mergeRemovalForInstall(sourcePath, strategy, currentContent, options = {}) {
   const source = await readMergeSource(sourcePath, strategy);
   if (currentContent === void 0) return source;
+  if (options.adoptExistingMcp) {
+    if (strategy === "codex-toml-mcp") {
+      const mismatched = mismatchedCodexTomlMcpServers(source, currentContent);
+      if (mismatched.length > 0) {
+        throw new MergeAdoptionMismatchError(`cannot adopt merged contribution: Codex MCP server content differs or is missing for ${mismatched.join(", ")}`);
+      }
+      return source;
+    }
+    if (strategy !== "json-deep") {
+      throw new MergeAdoptionMismatchError(`cannot adopt merged contribution: strategy ${strategy} is not supported for MCP adoption`);
+    }
+    const mismatch = firstMcpContributionMismatch(parseMergeDestination(currentContent, strategy), source);
+    if (mismatch) {
+      throw new MergeAdoptionMismatchError(`cannot adopt merged contribution: destination differs or is missing at ${mismatch}`);
+    }
+    return source;
+  }
   if (strategy === "codex-toml-mcp") {
     const existingServers = codexTomlMcpServerNames(currentContent);
     const servers = isRecord4(source.mcpServers) ? source.mcpServers : source;
@@ -1621,6 +1711,33 @@ function introducedMergeContent(base, incoming) {
   }
   return introduced;
 }
+function firstMcpContributionMismatch(current, incoming) {
+  if (!isRecord4(current) || !isRecord4(incoming)) return "$";
+  if (!isRecord4(current.mcpServers) || !isRecord4(incoming.mcpServers)) return "$.mcpServers";
+  for (const [name, incomingServer] of Object.entries(incoming.mcpServers)) {
+    if (!(name in current.mcpServers) || !sameMcpValue(current.mcpServers[name], incomingServer)) {
+      return `$.mcpServers.${name}`;
+    }
+  }
+  for (const [key, incomingValue] of Object.entries(incoming)) {
+    if (key === "mcpServers") continue;
+    if (!(key in current) || !sameMcpValue(current[key], incomingValue)) return `$.${key}`;
+  }
+  return void 0;
+}
+function combineMergeValues(existing, incoming) {
+  if (isRecord4(existing) && isRecord4(incoming)) {
+    const combined = { ...existing };
+    for (const [key, incomingValue] of Object.entries(incoming)) {
+      combined[key] = key in combined ? combineMergeValues(combined[key], incomingValue) : incomingValue;
+    }
+    return combined;
+  }
+  if (Array.isArray(existing) && Array.isArray(incoming)) {
+    return [...existing, ...incoming.filter((value) => !existing.some((current) => sameValue(current, value)))];
+  }
+  return incoming;
+}
 function removeIntroducedContent(current, removal) {
   for (const [key, removalValue] of Object.entries(removal)) {
     if (!(key in current)) continue;
@@ -1675,6 +1792,18 @@ function isRecord4(value) {
 function sameValue(left, right) {
   return JSON.stringify(left) === JSON.stringify(right);
 }
+function sameMcpValue(left, right) {
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((value, index) => sameMcpValue(value, right[index]));
+  }
+  if (isRecord4(left) || isRecord4(right)) {
+    if (!isRecord4(left) || !isRecord4(right)) return false;
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    return leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index] && sameMcpValue(left[key], right[key]));
+  }
+  return left === right;
+}
 function unquoteTomlKey2(key) {
   if (!key.startsWith('"')) return key;
   try {
@@ -2043,6 +2172,7 @@ async function uninstall(plan, options = {}) {
   const lock = await acquireApplyLock(plan.targetRoot, plan.adapter, transport, resolvedOptions.lock, scope);
   try {
     await assertBaseRevision(plan, transport);
+    await assertExactMergeRemovalPreconditions(removable, transport);
     const journal = {
       version: 1,
       mode: "uninstall",
@@ -2223,6 +2353,16 @@ async function applyOperation(operation, context) {
       if (operation.mergeCreatedDestination) {
         await transport.rm(operation.destPath);
       } else if (operation.mergeRemoval) {
+        if (operation.exactMergeRemoval) {
+          if (!await transport.pathExists(operation.destPath)) {
+            throw new Error(`Exact MCP retirement destination is missing: ${operation.relativeDestPath}`);
+          }
+          assertExactMcpMergeContribution(
+            operation.mergeRemoval,
+            operation.mergeStrategy,
+            await transport.readFile(operation.destPath)
+          );
+        }
         await removeMergeWithTransport(operation.destPath, operation.mergeStrategy, operation.mergeRemoval, transport);
       }
     } else {
@@ -2507,6 +2647,22 @@ async function assertBaseRevision(plan, transport) {
     throw new Error(`Install manifest changed since planning for ${plan.adapter}; replan needed`);
   }
 }
+async function assertExactMergeRemovalPreconditions(operations, transport) {
+  for (const operation of operations) {
+    if (!operation.exactMergeRemoval) continue;
+    if (!operation.mergeStrategy || !operation.mergeRemoval) {
+      throw new Error(`Invalid exact MCP retirement operation: ${operation.relativeDestPath}`);
+    }
+    if (!await transport.pathExists(operation.destPath)) {
+      throw new Error(`Exact MCP retirement destination is missing: ${operation.relativeDestPath}`);
+    }
+    assertExactMcpMergeContribution(
+      operation.mergeRemoval,
+      operation.mergeStrategy,
+      await transport.readFile(operation.destPath)
+    );
+  }
+}
 function isJournaledMutation(operation) {
   if (operation.semanticPlugin && (operation.action === "plugin" || operation.action === "remove")) return false;
   return operation.action === "create" || operation.action === "update" || operation.action === "remove";
@@ -3766,12 +3922,49 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
     if (op.mergeStrategy) {
       const existing2 = manifestByPath.get(op.relativeDestPath);
       const exists2 = await transport.pathExists(op.destPath);
-      const mergeRemoval = await mergeRemovalForInstall(op.sourcePath, op.mergeStrategy, exists2 ? await transport.readFile(op.destPath) : void 0);
+      const currentContent = exists2 ? await transport.readFile(op.destPath) : void 0;
+      const currentHash2 = exists2 ? await transport.hashPath(op.destPath) : void 0;
+      if (existing2 && workspaceOwner && !entryOwnedByWorkspace(existing2, workspaceOwner)) {
+        if (!await canAdoptLegacyUnownedEntry(existing2, op, transport)) {
+          operations.push(keepForeignManifestEntryOperation(existing2, targetRoot, workspaceOwner, op, currentHash2));
+          continue;
+        }
+      }
+      const incompleteMergeOwnership = existing2 && existing2.mergeStrategy && !("mergeCreatedDestination" in existing2 && existing2.mergeCreatedDestination === true) && !("mergeRemoval" in existing2 && hasMergeRemovalContent(existing2.mergeRemoval));
+      const adoptExisting = exists2 && (!existing2 || incompleteMergeOwnership) && options.forceConflict === true && op.artifactType === "mcp" && (op.mergeStrategy === "json-deep" || op.mergeStrategy === "codex-toml-mcp");
+      let mergeRemoval;
+      try {
+        mergeRemoval = await mergeRemovalForInstall(op.sourcePath, op.mergeStrategy, currentContent, { adoptExistingMcp: adoptExisting });
+      } catch (error) {
+        if (!(error instanceof MergeAdoptionMismatchError)) throw error;
+        operations.push({
+          ...op,
+          action: "conflict",
+          currentHash: currentHash2,
+          reason: error.message,
+          blockedReason: error.message
+        });
+        continue;
+      }
+      if (existing2 && "mergeRemoval" in existing2 && existing2.mergeRemoval) {
+        mergeRemoval = combineMergeRemovals(existing2.mergeRemoval, mergeRemoval);
+      }
       if (!exists2) {
         operations.push({ ...op, action: "create", mergeRemoval, mergeCreatedDestination: true, reason: "merge destination missing" });
         continue;
       }
-      const currentHash2 = await transport.hashPath(op.destPath);
+      if (adoptExisting) {
+        operations.push({
+          ...op,
+          action: "skip",
+          mergeRemoval,
+          mergeCreatedDestination: existing2?.mergeCreatedDestination,
+          currentHash: currentHash2,
+          manifestHash: existing2?.hash,
+          reason: existing2 ? "force repairing exact incomplete merge ownership" : "force adopting exact unmanaged merge contribution"
+        });
+        continue;
+      }
       if (existing2 && existing2.sourceHash === op.desiredHash) {
         operations.push(options.forceDrift ? { ...op, action: "update", mergeRemoval, mergeCreatedDestination: existing2.mergeCreatedDestination, currentHash: currentHash2, manifestHash: existing2.hash, reason: "force refreshing managed merge destination" } : { ...op, action: "skip", mergeRemoval: existing2.mergeRemoval, mergeCreatedDestination: existing2.mergeCreatedDestination, currentHash: currentHash2, manifestHash: existing2.hash, reason: "merged source already up to date" });
       } else {
@@ -4426,7 +4619,7 @@ async function createUninstallPlan(manifest, transport = localTransport) {
         composedFrom: entry.composedFrom,
         ...operationMetadataFromEntry2(entry)
       });
-    } else if (entry.mergeStrategy && !("mergeRemoval" in entry && entry.mergeRemoval !== void 0) && !("mergeCreatedDestination" in entry && entry.mergeCreatedDestination === true)) {
+    } else if (entry.mergeStrategy && !("mergeRemoval" in entry && hasMergeRemovalContent(entry.mergeRemoval)) && !("mergeCreatedDestination" in entry && entry.mergeCreatedDestination === true)) {
       operations.push(legacyMergeKeepOperation(entry, destPath));
     } else {
       operations.push({
@@ -4527,7 +4720,7 @@ async function createOwnershipUninstallPlan(manifest, remainingDesired, adapter,
         ...operationMetadataFromEntry2(entry),
         graphLockDigest: options.graphLockDigest
       });
-    } else if (entry.mergeStrategy && !("mergeRemoval" in entry && entry.mergeRemoval !== void 0) && !("mergeCreatedDestination" in entry && entry.mergeCreatedDestination === true)) {
+    } else if (entry.mergeStrategy && !("mergeRemoval" in entry && hasMergeRemovalContent(entry.mergeRemoval)) && !("mergeCreatedDestination" in entry && entry.mergeCreatedDestination === true)) {
       operations.push(legacyMergeKeepOperation(entry, destPath));
     } else {
       operations.push({
@@ -5396,8 +5589,8 @@ import { basename as basename9, join as join19, relative as relative4, resolve a
 import { readFile as readFile17 } from "fs/promises";
 import { join as join18 } from "path";
 import { parse as parse4, printParseErrorCode as printParseErrorCode2 } from "jsonc-parser";
-import { z as z5 } from "zod";
-var legacyArtifactTypeSchema = z5.enum([
+import { z as z6 } from "zod";
+var legacyArtifactTypeSchema = z6.enum([
   "instructions",
   "rules",
   "skills",
@@ -5408,33 +5601,33 @@ var legacyArtifactTypeSchema = z5.enum([
   "settings",
   "plugins"
 ]);
-var runtimeListSchema = z5.array(z5.string().min(1));
-var packageProvideBaseSchema = z5.object({
-  path: z5.string().min(1),
+var runtimeListSchema = z6.array(z6.string().min(1));
+var packageProvideBaseSchema = z6.object({
+  path: z6.string().min(1),
   format: artifactFormatSchema.optional(),
-  assets: z5.array(packageAssetSchema).optional(),
-  required: z5.boolean().optional()
+  assets: z6.array(packageAssetSchema).optional(),
+  required: z6.boolean().optional()
 });
-var packageItemSchema = z5.object({
+var packageItemSchema = z6.object({
   format: artifactFormatSchema.optional(),
-  requires: z5.array(packageItemRequireSchema).optional(),
-  suggests: z5.array(packageItemSuggestSchema).optional(),
-  compose: z5.array(packageComposeEntrySchema).optional(),
+  requires: z6.array(packageItemRequireSchema).optional(),
+  suggests: z6.array(packageItemSuggestSchema).optional(),
+  compose: z6.array(packageComposeEntrySchema).optional(),
   runtimes: runtimeListSchema.optional()
 });
-var packageDependencySchema = z5.object({
-  source: z5.string().min(1),
-  ref: z5.string().min(1).optional(),
-  version: z5.string().min(1).optional(),
-  select: z5.array(z5.string().min(1)).optional(),
-  mode: z5.enum(["pinned", "tracking"]).optional(),
-  optional: z5.boolean().optional(),
-  integrity: z5.string().min(1).optional(),
+var packageDependencySchema = z6.object({
+  source: z6.string().min(1),
+  ref: z6.string().min(1).optional(),
+  version: z6.string().min(1).optional(),
+  select: z6.array(z6.string().min(1)).optional(),
+  mode: z6.enum(["pinned", "tracking"]).optional(),
+  optional: z6.boolean().optional(),
+  integrity: z6.string().min(1).optional(),
   runtimes: runtimeListSchema.optional()
 });
 var packageSuggestionSchema = packageDependencySchema.extend({
-  reason: z5.string().min(1).optional(),
-  when: z5.string().min(1).optional()
+  reason: z6.string().min(1).optional(),
+  when: z6.string().min(1).optional()
 });
 var packageProvideV1Schema = packageProvideBaseSchema.extend({
   type: legacyArtifactTypeSchema
@@ -5442,35 +5635,35 @@ var packageProvideV1Schema = packageProvideBaseSchema.extend({
 var packageProvideSchema = packageProvideBaseSchema.extend({
   type: artifactTypeSchema,
   runtimes: runtimeListSchema.optional(),
-  items: z5.record(z5.string().min(1), packageItemSchema).optional()
+  items: z6.record(z6.string().min(1), packageItemSchema).optional()
 });
-var packageManifestV1Schema = z5.object({
-  schemaVersion: z5.literal(1),
-  name: z5.string().min(1),
-  version: z5.string().min(1),
-  provides: z5.array(packageProvideV1Schema).min(1)
+var packageManifestV1Schema = z6.object({
+  schemaVersion: z6.literal(1),
+  name: z6.string().min(1),
+  version: z6.string().min(1),
+  provides: z6.array(packageProvideV1Schema).min(1)
 });
-var packageManifestV2Schema = z5.object({
-  schemaVersion: z5.literal(2),
-  name: z5.string().min(1),
-  version: z5.string().min(1),
+var packageManifestV2Schema = z6.object({
+  schemaVersion: z6.literal(2),
+  name: z6.string().min(1),
+  version: z6.string().min(1),
   runtimes: runtimeListSchema.optional(),
-  requires: z5.record(z5.string().min(1), packageDependencySchema).optional(),
-  suggests: z5.record(z5.string().min(1), packageSuggestionSchema).optional(),
-  compose: z5.array(packageComposeEntrySchema).optional(),
-  provides: z5.array(packageProvideSchema).default([])
+  requires: z6.record(z6.string().min(1), packageDependencySchema).optional(),
+  suggests: z6.record(z6.string().min(1), packageSuggestionSchema).optional(),
+  compose: z6.array(packageComposeEntrySchema).optional(),
+  provides: z6.array(packageProvideSchema).default([])
 }).superRefine((manifest, ctx) => {
   const hasProvides = manifest.provides.length > 0;
   const hasRequires = Object.keys(manifest.requires ?? {}).length > 0;
   if (!hasProvides && !hasRequires) {
     ctx.addIssue({
-      code: z5.ZodIssueCode.custom,
+      code: z6.ZodIssueCode.custom,
       path: ["provides"],
       message: "OpenPack v2 manifest must declare at least one provides entry or one requires dependency"
     });
   }
 });
-var packageManifestSchema = z5.union([packageManifestV1Schema, packageManifestV2Schema]);
+var packageManifestSchema = z6.union([packageManifestV1Schema, packageManifestV2Schema]);
 var openPackManifestNames = ["openpack.json", "openpack.jsonc"];
 var legacyPackageManifestNames = ["agentwheel.json", "agentwheel.jsonc"];
 var packageManifestNames = [...openPackManifestNames, ...legacyPackageManifestNames];
@@ -5664,7 +5857,7 @@ var LocalSourceDriver = class {
   async scan(resolved) {
     const artifacts = await this.list(resolved);
     const findings = [];
-    if (!artifacts.some((artifact) => artifact.type === "instructions")) {
+    if (!resolved.packageName && !artifacts.some((artifact) => artifact.type === "instructions")) {
       findings.push({ level: "warning", message: "No instructions.md or AGENTS.md found", path: resolved.resolvedPath });
     }
     for (const artifact of artifacts.filter((item) => item.type === "skills" && item.kind === "dir")) {
@@ -5730,6 +5923,7 @@ async function listFromManifest(root, packageName) {
         if ((provide.type === "skills" || provide.type === "plugins" || provide.type === "subagents") && entry.isDirectory()) {
           artifacts.push(await artifactForDir(provide.type, entry.name, child, join19(provide.path, entry.name), packageName, provide, manifest, entry.name));
         } else if (entry.isFile()) {
+          if (provide.type === "skills" && entry.name.toLowerCase() === "readme.md") continue;
           const name = provide.type === "rules" && entry.name.endsWith(".md") ? entry.name : entry.name;
           artifacts.push(await artifactForFile(provide.type, name, child, join19(provide.path, entry.name), packageName, provide, manifest, name));
         }
@@ -5949,9 +6143,9 @@ function cachePathFor(packageName, cacheRoot) {
 
 // src/source/git.ts
 import { execFile as execFile4 } from "child_process";
-import { cp as cp2, mkdir as mkdir13, rename as rename3, rm as rm6, writeFile as writeFile15 } from "fs/promises";
+import { cp as cp2, mkdir as mkdir14, rename as rename3, rm as rm7 } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { basename as basename11, dirname as dirname16, join as join22, resolve as resolve7 } from "path";
+import { basename as basename11, dirname as dirname17, join as join23, resolve as resolve7 } from "path";
 import { promisify as promisify4 } from "util";
 
 // src/source/auth.ts
@@ -6023,6 +6217,209 @@ function isMissingFile(error) {
   return isRecord8(error) && error.code === "ENOENT";
 }
 
+// src/source/cache.ts
+import { randomUUID } from "crypto";
+import { mkdir as mkdir13, readdir as readdir2, readFile as readFile19, rm as rm6, stat as stat4, writeFile as writeFile15 } from "fs/promises";
+import { dirname as dirname16, join as join22 } from "path";
+var snapshotNamePattern = /^(.*)-([0-9a-f]{12})$/i;
+var leaseMarker = ".agentwheel-lease-";
+async function pruneGitCache(cacheRoot, options = {}) {
+  if (!await pathExists(cacheRoot)) return { removedPaths: [], retainedPaths: [] };
+  if (options.maintenanceLockHeld) return pruneGitCacheUnlocked(cacheRoot, options);
+  return withGitCacheMaintenanceLock(
+    cacheRoot,
+    options.cacheLockTimeoutMs ?? 3e4,
+    () => pruneGitCacheUnlocked(cacheRoot, options)
+  );
+}
+async function withGitCacheMaintenanceLock(cacheRoot, timeoutMs, fn) {
+  const lockPath = join22(cacheRoot, ".maintenance.lock");
+  await mkdir13(cacheRoot, { recursive: true });
+  const started = Date.now();
+  while (true) {
+    try {
+      await mkdir13(lockPath);
+      await writeFile15(
+        join22(lockPath, "owner.json"),
+        JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() }),
+        "utf8"
+      );
+      break;
+    } catch (error) {
+      if (!isAlreadyExists3(error)) throw error;
+      if (await removeStaleMaintenanceLock(lockPath)) continue;
+      if (Date.now() - started > timeoutMs) {
+        throw new Error(`Timed out waiting for git cache maintenance lock at ${lockPath}`);
+      }
+      await new Promise((resolve23) => setTimeout(resolve23, 50));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    await rm6(lockPath, { recursive: true, force: true });
+  }
+}
+async function createGitSnapshotLease(snapshotPath) {
+  const leasePath = `${snapshotPath}${leaseMarker}${process.pid}-${randomUUID()}`;
+  await writeFile15(leasePath, JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() }), {
+    encoding: "utf8",
+    flag: "wx"
+  });
+  return leasePath;
+}
+async function releaseGitSnapshotLease(leasePath) {
+  if (leasePath) await rm6(leasePath, { force: true });
+}
+async function removeGeneratedEntries(root, preserveGit) {
+  let entries;
+  try {
+    entries = await readdir2(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const path = join22(root, entry.name);
+    if (isIgnoredGeneratedEntry(entry.name) && !(preserveGit && entry.name === ".git")) {
+      await rm6(path, { recursive: true, force: true });
+    } else if (entry.isDirectory()) {
+      await removeGeneratedEntries(path, preserveGit);
+    }
+  }
+}
+async function pruneGitCacheUnlocked(cacheRoot, options) {
+  const referencedCommits = await referencedGraphLockCommits(join22(dirname16(cacheRoot), "locks"));
+  const entries = await readdir2(cacheRoot, { withFileTypes: true });
+  const groups = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const match = snapshotNamePattern.exec(entry.name);
+    if (!match) continue;
+    const checkoutPath = join22(cacheRoot, match[1]);
+    if (!await pathExists(join22(checkoutPath, ".git"))) continue;
+    const snapshotPath = join22(cacheRoot, entry.name);
+    const snapshotStats = await stat4(snapshotPath);
+    const snapshots = groups.get(checkoutPath) ?? [];
+    snapshots.push({ path: snapshotPath, commitPrefix: match[2].toLowerCase(), modifiedAt: snapshotStats.mtimeMs });
+    groups.set(checkoutPath, snapshots);
+  }
+  const keepCount = Math.max(1, Math.floor(options.keepSnapshots ?? 3));
+  const removedPaths = [];
+  const retainedPaths = [];
+  for (const [checkoutPath, snapshots] of groups) {
+    if (!options.dryRun) await removeGeneratedEntries(checkoutPath, true);
+    snapshots.sort((a, b) => b.modifiedAt - a.modifiedAt || a.path.localeCompare(b.path));
+    const keep = /* @__PURE__ */ new Set();
+    for (const snapshot of snapshots.slice(0, keepCount)) keep.add(snapshot.path);
+    if (options.currentSnapshot) keep.add(options.currentSnapshot);
+    for (const snapshot of snapshots) {
+      if ([...referencedCommits].some((commit) => commit.startsWith(snapshot.commitPrefix))) keep.add(snapshot.path);
+      if (await hasLiveSnapshotLease(snapshot.path, options.dryRun === true)) keep.add(snapshot.path);
+    }
+    for (const snapshot of snapshots) {
+      if (keep.has(snapshot.path)) {
+        retainedPaths.push(snapshot.path);
+        if (!options.dryRun) await removeGeneratedEntries(snapshot.path, false);
+      } else {
+        removedPaths.push(snapshot.path);
+        if (!options.dryRun) await rm6(snapshot.path, { recursive: true, force: true });
+      }
+    }
+  }
+  return { removedPaths, retainedPaths };
+}
+async function referencedGraphLockCommits(lockRoot) {
+  const commits = /* @__PURE__ */ new Set();
+  await walkGraphLocks(lockRoot, (value) => collectResolvedCommits(value, commits));
+  return commits;
+}
+async function walkGraphLocks(root, visit) {
+  let entries;
+  try {
+    entries = await readdir2(root, { withFileTypes: true });
+  } catch (error) {
+    if (isNotFound(error)) return;
+    throw new Error(`Cannot inspect graph-lock directory ${root}; cache prune aborted: ${errorMessage3(error)}`);
+  }
+  for (const entry of entries) {
+    const path = join22(root, entry.name);
+    if (entry.isDirectory()) {
+      await walkGraphLocks(path, visit);
+    } else if (entry.isFile() && entry.name.endsWith(".graph-lock.json")) {
+      try {
+        visit(JSON.parse(await readFile19(path, "utf8")));
+      } catch (error) {
+        throw new Error(`Cannot read graph lock ${path}; cache prune aborted: ${errorMessage3(error)}`);
+      }
+    }
+  }
+}
+async function hasLiveSnapshotLease(snapshotPath, dryRun) {
+  const directory = dirname16(snapshotPath);
+  const prefix = `${snapshotPath.slice(directory.length + 1)}${leaseMarker}`;
+  const entries = await readdir2(directory, { withFileTypes: true });
+  let live = false;
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.startsWith(prefix)) continue;
+    const leasePath = join22(directory, entry.name);
+    try {
+      const value = JSON.parse(await readFile19(leasePath, "utf8"));
+      if (typeof value.pid !== "number" || !Number.isSafeInteger(value.pid) || value.pid <= 0) {
+        live = true;
+      } else if (isProcessAlive(value.pid)) {
+        live = true;
+      } else if (!dryRun) {
+        await rm6(leasePath, { force: true });
+      }
+    } catch {
+      live = true;
+    }
+  }
+  return live;
+}
+async function removeStaleMaintenanceLock(lockPath) {
+  try {
+    const value = JSON.parse(await readFile19(join22(lockPath, "owner.json"), "utf8"));
+    if (typeof value.pid !== "number" || !Number.isSafeInteger(value.pid) || value.pid <= 0 || isProcessAlive(value.pid)) {
+      return false;
+    }
+    await rm6(lockPath, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code !== "ESRCH";
+  }
+}
+function collectResolvedCommits(value, commits) {
+  if (Array.isArray(value)) {
+    for (const item of value) collectResolvedCommits(item, commits);
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, item] of Object.entries(value)) {
+    if (key === "resolvedCommit" && typeof item === "string" && /^[0-9a-f]{12,40}$/i.test(item)) {
+      commits.add(item.toLowerCase());
+    }
+    collectResolvedCommits(item, commits);
+  }
+}
+function isAlreadyExists3(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function errorMessage3(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
 // src/source/git.ts
 var execFileAsync4 = promisify4(execFile4);
 var GitSourceDriver = class {
@@ -6045,12 +6442,12 @@ var GitSourceDriver = class {
   async fetch(resolved) {
     return withFilesystemLock(`${resolved.resolvedPath}.lock`, resolved.cacheLockTimeoutMs ?? 3e4, async () => {
       const parsed = parseGitSource(resolved.source);
-      await mkdir13(resolve7(resolved.resolvedPath, ".."), { recursive: true });
-      if (!await pathExists(join22(resolved.resolvedPath, ".git"))) {
+      await mkdir14(resolve7(resolved.resolvedPath, ".."), { recursive: true });
+      if (!await pathExists(join23(resolved.resolvedPath, ".git"))) {
         if (resolved.frozenLock) {
           throw new Error(`Frozen lock requires cached git checkout at ${resolved.resolvedPath}`);
         }
-        await rm6(resolved.resolvedPath, { recursive: true, force: true });
+        await rm7(resolved.resolvedPath, { recursive: true, force: true });
         await git([...await gitAuthArguments(parsed.url), "clone", parsed.url, resolved.resolvedPath]);
       } else if (!resolved.frozenLock) {
         await git([
@@ -6076,9 +6473,24 @@ var GitSourceDriver = class {
           await git(["-C", resolved.resolvedPath, "checkout", "--detach", ref]);
         }
       }
+      await removeGeneratedEntries(resolved.resolvedPath, true);
       const { stdout } = await git(["-C", resolved.resolvedPath, "rev-parse", "HEAD"]);
       const resolvedCommit = stdout.trim();
-      const snapshotPath = await snapshotCheckout(resolved.resolvedPath, resolvedCommit);
+      const cacheRoot = dirname17(resolved.resolvedPath);
+      const snapshot = await withGitCacheMaintenanceLock(
+        cacheRoot,
+        resolved.cacheLockTimeoutMs ?? 3e4,
+        async () => {
+          const path = await snapshotCheckout(resolved.resolvedPath, resolvedCommit);
+          const leasePath = await createGitSnapshotLease(path);
+          await pruneGitCache(cacheRoot, {
+            currentSnapshot: path,
+            maintenanceLockHeld: true
+          });
+          return { path, leasePath };
+        }
+      );
+      const snapshotPath = snapshot.path;
       const manifest = await readPackageManifest(snapshotPath);
       return {
         ...resolved,
@@ -6086,9 +6498,10 @@ var GitSourceDriver = class {
         packageName: manifest?.name,
         packageVersion: manifest?.version,
         resolvedCommit,
-        sourceHash: await hashPath(snapshotPath)
+        sourceHash: await hashPath(snapshotPath),
+        cacheLeasePath: snapshot.leasePath
       };
-    });
+    }, "git cache");
   }
   async list(resolved) {
     return this.local.list({ ...resolved, driver: "local" });
@@ -6121,58 +6534,37 @@ function parseGitSource(source) {
   throw new Error(`Invalid git source: ${source}`);
 }
 function cachePathFor2(url, cacheRoot) {
-  const root = cacheRoot ? resolve7(cacheRoot) : join22(homedir3(), ".agentwheel", "cache");
+  const root = cacheRoot ? resolve7(cacheRoot) : join23(homedir3(), ".agentwheel", "cache");
   const slug2 = url.replace(/^[a-z]+:\/\//i, "").replace(/\.git$/i, "").replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "");
-  return join22(root, slug2 || basename11(url));
+  return join23(root, slug2 || basename11(url));
 }
 async function git(args) {
   return execFileAsync4("git", args, { maxBuffer: 1024 * 1024 * 10 });
 }
 async function snapshotCheckout(checkoutPath, commit) {
-  const snapshotPath = join22(dirname16(checkoutPath), `${basename11(checkoutPath)}-${commit.slice(0, 12)}`);
+  const snapshotPath = join23(dirname17(checkoutPath), `${basename11(checkoutPath)}-${commit.slice(0, 12)}`);
   if (await pathExists(snapshotPath)) return snapshotPath;
-  const tempPath = join22(dirname16(checkoutPath), `${basename11(snapshotPath)}.tmp-${process.pid}-${Date.now()}`);
-  await rm6(tempPath, { recursive: true, force: true });
-  await cp2(checkoutPath, tempPath, { recursive: true, dereference: true });
-  await rm6(join22(tempPath, ".git"), { recursive: true, force: true });
+  const tempPath = join23(dirname17(checkoutPath), `${basename11(snapshotPath)}.tmp-${process.pid}-${Date.now()}`);
+  await rm7(tempPath, { recursive: true, force: true });
+  await cp2(checkoutPath, tempPath, {
+    recursive: true,
+    dereference: true,
+    filter: (path) => !isIgnoredGeneratedEntry(basename11(path))
+  });
+  await rm7(join23(tempPath, ".git"), { recursive: true, force: true });
   try {
     await rename3(tempPath, snapshotPath);
   } catch (error) {
-    if (!isAlreadyExists2(error)) throw error;
-    await rm6(tempPath, { recursive: true, force: true });
+    if (!isAlreadyExists(error)) throw error;
+    await rm7(tempPath, { recursive: true, force: true });
     return snapshotPath;
   }
   return snapshotPath;
 }
-async function withFilesystemLock(lockPath, timeoutMs, fn) {
-  await mkdir13(dirname16(lockPath), { recursive: true });
-  const started = Date.now();
-  while (true) {
-    try {
-      await mkdir13(lockPath);
-      await writeFile15(join22(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() }), "utf8");
-      break;
-    } catch (error) {
-      if (!isAlreadyExists2(error)) throw error;
-      if (Date.now() - started > timeoutMs) {
-        throw new Error(`Timed out waiting for git cache lock at ${lockPath}`);
-      }
-      await new Promise((resolve23) => setTimeout(resolve23, 50));
-    }
-  }
-  try {
-    return await fn();
-  } finally {
-    await rm6(lockPath, { recursive: true, force: true });
-  }
-}
-function isAlreadyExists2(error) {
-  return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
-}
 
 // src/source/mcp-registry.ts
-import { mkdir as mkdir14, writeFile as writeFile16 } from "fs/promises";
-import { basename as basename12, dirname as dirname17, join as join23, resolve as resolve8 } from "path";
+import { mkdir as mkdir15, writeFile as writeFile16 } from "fs/promises";
+import { basename as basename12, dirname as dirname18, join as join24, resolve as resolve8 } from "path";
 var registryBaseUrl = "https://registry.modelcontextprotocol.io/v0.1";
 var sourcePrefix2 = "mcp-registry:";
 var McpRegistrySourceDriver = class {
@@ -6238,7 +6630,7 @@ var McpRegistrySourceDriver = class {
     return this.local.list({ ...resolved, driver: "local" });
   }
   async scan(resolved) {
-    if (!await pathExists(join23(resolved.resolvedPath, "mcp"))) {
+    if (!await pathExists(join24(resolved.resolvedPath, "mcp"))) {
       return { ok: false, findings: [{ level: "error", message: "MCP registry source has no generated mcp artifact" }] };
     }
     return { ok: true, findings: [] };
@@ -6278,9 +6670,9 @@ function isSafeHttpUrl(value) {
 }
 async function writeGeneratedPackage2(root, server) {
   const serverId = installNameFor3(server.serverName);
-  const mcpPath = join23(root, "mcp", `${serverId}.json`);
-  await mkdir14(dirname17(mcpPath), { recursive: true });
-  await writeFile16(join23(root, "openpack.json"), `${JSON.stringify({
+  const mcpPath = join24(root, "mcp", `${serverId}.json`);
+  await mkdir15(dirname18(mcpPath), { recursive: true });
+  await writeFile16(join24(root, "openpack.json"), `${JSON.stringify({
     schemaVersion: 2,
     name: `mcp-registry/${server.serverName}`,
     version: server.version ?? "latest",
@@ -6301,20 +6693,23 @@ function installNameFor3(serverName) {
   return basename12(serverName).replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "mcp-server";
 }
 function cachePathFor3(serverName, cacheRoot) {
-  const root = cacheRoot ? resolve8(cacheRoot) : join23(process.env.HOME ?? ".", ".agentwheel", "cache");
+  const root = cacheRoot ? resolve8(cacheRoot) : join24(process.env.HOME ?? ".", ".agentwheel", "cache");
   const slug2 = `mcp-registry-${serverName}`.replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "");
-  return join23(root, slug2 || "mcp-registry-server");
+  return join24(root, slug2 || "mcp-registry-server");
 }
 
 // src/source/skillkit.ts
-import { cp as cp3, mkdir as mkdir15, readFile as readFile19, rm as rm7 } from "fs/promises";
+import { createHash as createHash6, randomUUID as randomUUID2 } from "crypto";
+import { execFile as execFile5 } from "child_process";
+import { cp as cp3, mkdir as mkdir16, readFile as readFile20, rename as rename4, rm as rm8 } from "fs/promises";
 import { homedir as homedir4 } from "os";
-import { basename as basename14, dirname as dirname19, join as join25, resolve as resolve9 } from "path";
+import { basename as basename14, dirname as dirname20, join as join26, resolve as resolve9 } from "path";
+import { promisify as promisify5 } from "util";
 import * as defaultSkillKit from "@skillkit/core";
 
 // src/source/skill-artifacts.ts
-import { readdir as readdir2, stat as stat4 } from "fs/promises";
-import { basename as basename13, dirname as dirname18, extname as extname2, join as join24 } from "path";
+import { readdir as readdir3, stat as stat5 } from "fs/promises";
+import { basename as basename13, dirname as dirname19, extname as extname2, join as join25 } from "path";
 async function artifactsFromSkillPaths(paths, packageName) {
   const artifacts = [];
   const seen = /* @__PURE__ */ new Set();
@@ -6334,16 +6729,16 @@ async function discoverSkillPaths(root) {
   return paths;
 }
 async function artifactFromSkillPath(item, packageName) {
-  const stats = await stat4(item.path);
+  const stats = await stat5(item.path);
   if (stats.isDirectory()) {
-    const skillMd = join24(item.path, "SKILL.md");
+    const skillMd = join25(item.path, "SKILL.md");
     if (!await pathExists(skillMd)) return void 0;
     const name = sanitizeSkillName(item.name ?? basename13(item.path));
     return {
       type: "skills",
       name,
       sourcePath: item.path,
-      relativePath: join24("skills", name),
+      relativePath: join25("skills", name),
       kind: "dir",
       hash: await hashPath(item.path),
       packageName,
@@ -6351,13 +6746,13 @@ async function artifactFromSkillPath(item, packageName) {
     };
   }
   if (stats.isFile() && basename13(item.path).toLowerCase() === "skill.md") {
-    const dir = dirname18(item.path);
+    const dir = dirname19(item.path);
     const name = sanitizeSkillName(item.name ?? basename13(dir));
     return {
       type: "skills",
       name,
       sourcePath: dir,
-      relativePath: join24("skills", name),
+      relativePath: join25("skills", name),
       kind: "dir",
       hash: await hashPath(dir),
       packageName,
@@ -6370,7 +6765,7 @@ async function artifactFromSkillPath(item, packageName) {
       type: "skills",
       name,
       sourcePath: item.path,
-      relativePath: join24("skills", `${name}.md`),
+      relativePath: join25("skills", `${name}.md`),
       kind: "file",
       hash: await hashPath(item.path),
       packageName,
@@ -6381,14 +6776,14 @@ async function artifactFromSkillPath(item, packageName) {
 }
 async function walk(dir, paths) {
   if (!await pathExists(dir)) return;
-  const entries = await readdir2(dir, { withFileTypes: true });
+  const entries = await readdir3(dir, { withFileTypes: true });
   if (entries.some((entry) => entry.isFile() && entry.name === "SKILL.md")) {
     paths.push({ path: dir });
     return;
   }
   for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
     if (!entry.isDirectory() || entry.name === ".git" || entry.name === "node_modules") continue;
-    await walk(join24(dir, entry.name), paths);
+    await walk(join25(dir, entry.name), paths);
   }
 }
 function sanitizeSkillName(name) {
@@ -6396,12 +6791,14 @@ function sanitizeSkillName(name) {
 }
 
 // src/source/skillkit.ts
+var execFileAsync5 = promisify5(execFile5);
 var SkillKitSourceDriver = class {
   constructor(core = defaultSkillKit) {
     this.core = core;
   }
   core;
   name = "skillkit";
+  inflightFetches = /* @__PURE__ */ new Map();
   async resolve(source, options = {}) {
     const spec = parseSkillKitSource(source);
     if (await pathExists(spec)) {
@@ -6415,14 +6812,17 @@ var SkillKitSourceDriver = class {
         sourceHash: await hashPath(resolvedPath)
       };
     }
+    const cacheIdentity = normalizeImmutableCacheIdentity(options.cacheIdentity) ?? immutableCommit(options.ref);
     return {
       driver: this.name,
       source,
-      resolvedPath: cachePathFor4(spec, options.cacheRoot),
+      resolvedPath: cachePathFor4(spec, options.cacheRoot, cacheIdentity),
       packageName: `skillkit/${packageSlug(spec)}`,
       mode: options.mode ?? "tracking",
       requestedRef: options.ref,
-      frozenLock: options.frozenLock
+      cacheIdentity,
+      frozenLock: options.frozenLock,
+      cacheLockTimeoutMs: options.cacheLockTimeoutMs
     };
   }
   async fetch(resolved) {
@@ -6430,35 +6830,104 @@ var SkillKitSourceDriver = class {
     if (await pathExists(spec)) {
       return resolved;
     }
+    const requestedCommit = immutableCommit(resolved.requestedRef);
+    const immutableCacheIdentity = resolved.cacheIdentity ?? requestedCommit;
     if (resolved.frozenLock) {
+      if (!immutableCacheIdentity) {
+        throw new Error("Frozen lock requires cached SkillKit source identified by an immutable cache identity.");
+      }
       if (!await pathExists(resolved.resolvedPath)) {
         throw new Error(`Frozen lock requires cached SkillKit source at ${resolved.resolvedPath}`);
       }
       return {
         ...resolved,
+        resolvedCommit: requestedCommit,
+        cacheIdentity: immutableCacheIdentity,
         sourceHash: await hashPath(resolved.resolvedPath)
       };
     }
+    if (immutableCacheIdentity && await pathExists(resolved.resolvedPath)) {
+      return {
+        ...resolved,
+        resolvedCommit: requestedCommit,
+        cacheIdentity: immutableCacheIdentity,
+        sourceHash: await hashPath(resolved.resolvedPath)
+      };
+    }
+    const specCachePath = cachePathFor4(spec, dirname20(dirname20(resolved.resolvedPath)));
+    const refIdentity = resolved.requestedRef ?? "default";
+    const lockPath = `${specCachePath}.ref-${createHash6("sha256").update(refIdentity).digest("hex")}.lock`;
+    const inflightKey = `${lockPath}\0${requestedCommit ?? "movable"}`;
+    const inflight = this.inflightFetches.get(inflightKey);
+    if (inflight) return inflight;
+    const fetchPromise = this.materializeRemote(resolved, spec, specCachePath, lockPath, requestedCommit);
+    this.inflightFetches.set(inflightKey, fetchPromise);
+    try {
+      return await fetchPromise;
+    } finally {
+      if (this.inflightFetches.get(inflightKey) === fetchPromise) this.inflightFetches.delete(inflightKey);
+    }
+  }
+  async materializeRemote(resolved, spec, specCachePath, lockPath, requestedCommit) {
     const providerSpec = normalizeProviderSource(spec);
     const provider = this.core.detectProvider?.(providerSpec);
     if (!provider?.clone) {
       throw new Error("SkillKit provider API unavailable or cannot resolve source. Expected @skillkit/core detectProvider().clone().");
     }
-    await mkdir15(dirname19(resolved.resolvedPath), { recursive: true });
-    const result = await provider.clone(providerSpec, resolved.resolvedPath, {});
-    if (!result.success || !result.path) {
-      throw new Error(`SkillKit provider failed to fetch ${spec}: ${result.error ?? "unknown error"}`);
-    }
-    if (resolve9(result.path) !== resolve9(resolved.resolvedPath)) {
-      await rm7(resolved.resolvedPath, { recursive: true, force: true });
-      await cp3(result.path, resolved.resolvedPath, { recursive: true, dereference: true });
-    }
-    if (result.tempRoot) {
-      await rm7(result.tempRoot, { recursive: true, force: true });
-    }
+    const materialized = await withFilesystemLock(lockPath, resolved.cacheLockTimeoutMs ?? 3e4, async () => {
+      const immutablePath = requestedCommit ? cachePathFor4(spec, dirname20(dirname20(specCachePath)), requestedCommit) : void 0;
+      if (immutablePath && await pathExists(immutablePath)) {
+        return { path: immutablePath, commit: requestedCommit, cacheIdentity: requestedCommit };
+      }
+      await mkdir16(dirname20(specCachePath), { recursive: true });
+      const candidatePath = `${specCachePath}.agentwheel-tmp-${process.pid}-${randomUUID2()}`;
+      const publishPath = `${candidatePath}.publish`;
+      let result;
+      try {
+        const requestedRef = resolved.requestedRef;
+        result = await provider.clone(providerSpec, candidatePath, requestedCommit || !requestedRef ? {} : { branch: requestedRef });
+        if (!result.success || !result.path) {
+          throw new Error(`SkillKit provider failed to fetch ${spec}: ${result.error ?? "unknown error"}`);
+        }
+        if (requestedCommit && requestedRef) {
+          if (!result.tempRoot) {
+            throw new Error(`SkillKit provider cannot materialize commit ${requestedRef}: clone result has no git checkout root`);
+          }
+          await checkoutCommit(result.tempRoot, requestedRef);
+        }
+        const resolvedIdentity = await resolveCloneIdentity(result);
+        if (requestedCommit && !resolvedIdentity.commit?.startsWith(requestedCommit)) {
+          throw new Error(
+            `SkillKit provider resolved ${resolvedIdentity.commit ?? "non-Git content"} instead of requested commit ${requestedCommit}`
+          );
+        }
+        const cachePath = cachePathFor4(spec, dirname20(dirname20(specCachePath)), resolvedIdentity.cacheKey);
+        if (await pathExists(cachePath)) {
+          return { path: cachePath, commit: resolvedIdentity.commit, cacheIdentity: resolvedIdentity.cacheKey };
+        }
+        const publishCandidate = resolve9(result.path) === resolve9(candidatePath) ? candidatePath : publishPath;
+        if (publishCandidate === publishPath) await cp3(result.path, publishPath, { recursive: true, dereference: true });
+        try {
+          await rename4(publishCandidate, cachePath);
+        } catch (error) {
+          if (!isAlreadyExists(error) && !isDirectoryNotEmpty(error)) throw error;
+          await rm8(publishCandidate, { recursive: true, force: true });
+        }
+        return { path: cachePath, commit: resolvedIdentity.commit, cacheIdentity: resolvedIdentity.cacheKey };
+      } finally {
+        await rm8(candidatePath, { recursive: true, force: true });
+        await rm8(publishPath, { recursive: true, force: true });
+        if (result?.tempRoot) {
+          await rm8(result.tempRoot, { recursive: true, force: true });
+        }
+      }
+    });
     return {
       ...resolved,
-      sourceHash: await hashPath(resolved.resolvedPath)
+      resolvedPath: materialized.path,
+      resolvedCommit: materialized.commit,
+      cacheIdentity: materialized.cacheIdentity,
+      sourceHash: await hashPath(materialized.path)
     };
   }
   async list(resolved) {
@@ -6488,9 +6957,9 @@ var SkillKitSourceDriver = class {
       throw new Error("SkillKit translateSkill API unavailable");
     }
     for (const skill of this.discover(resolved.resolvedPath)) {
-      const skillMd = join25(skill.path, "SKILL.md");
+      const skillMd = join26(skill.path, "SKILL.md");
       if (await pathExists(skillMd)) {
-        this.core.translateSkill(await readFile19(skillMd, "utf8"), "openclaw", { sourceFilename: "SKILL.md" });
+        this.core.translateSkill(await readFile20(skillMd, "utf8"), "openclaw", { sourceFilename: "SKILL.md" });
       }
     }
     return resolved;
@@ -6518,9 +6987,11 @@ function normalizeProviderSource(spec) {
   if (spec.startsWith("git:https://github.com/")) return spec.slice("git:".length);
   return spec;
 }
-function cachePathFor4(spec, cacheRoot) {
-  const root = cacheRoot ? resolve9(cacheRoot) : join25(homedir4(), ".agentwheel", "cache");
-  return join25(root, "skillkit", packageSlug(spec));
+function cachePathFor4(spec, cacheRoot, immutableIdentity) {
+  const root = cacheRoot ? resolve9(cacheRoot) : join26(homedir4(), ".agentwheel", "cache");
+  const sourceIdentity = createHash6("sha256").update(spec).digest("hex");
+  const snapshotIdentity = immutableIdentity ? `-${immutableIdentity.toLowerCase()}` : "";
+  return join26(root, "skillkit", `${packageSlug(spec)}-${sourceIdentity}${snapshotIdentity}`);
 }
 function packageSlug(spec) {
   return spec.replace(/^[a-z]+:\/\//i, "").replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "source";
@@ -6530,10 +7001,40 @@ function mapSeverity(severity) {
   if (severity === "medium" || severity === "low") return "warning";
   return "info";
 }
+function isDirectoryNotEmpty(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOTEMPTY";
+}
+function immutableCommit(ref) {
+  return ref && /^[0-9a-f]{7,40}$/i.test(ref) ? ref.toLowerCase() : void 0;
+}
+async function resolveCloneIdentity(result) {
+  if (result.resolvedCommit && /^[0-9a-f]{40}$/i.test(result.resolvedCommit)) {
+    const commit = result.resolvedCommit.toLowerCase();
+    return { cacheKey: commit, commit };
+  }
+  const checkoutRoot = result.tempRoot ?? result.path;
+  if (!checkoutRoot) throw new Error("SkillKit provider clone has no checkout path");
+  try {
+    const { stdout } = await execFileAsync5("git", ["-C", checkoutRoot, "rev-parse", "HEAD"]);
+    const commit = stdout.trim().toLowerCase();
+    if (!/^[0-9a-f]{40}$/.test(commit)) throw new Error(`invalid commit '${commit}'`);
+    return { cacheKey: commit, commit };
+  } catch {
+    return { cacheKey: `content-${await hashPath(result.path)}` };
+  }
+}
+async function checkoutCommit(root, commit) {
+  try {
+    await execFileAsync5("git", ["-C", root, "checkout", "--detach", commit]);
+  } catch {
+    await execFileAsync5("git", ["-C", root, "fetch", "origin", commit]);
+    await execFileAsync5("git", ["-C", root, "checkout", "--detach", commit]);
+  }
+}
 
 // src/source/vercel-skills.ts
-import { stat as stat5 } from "fs/promises";
-import { basename as basename15, join as join26, relative as relative5, resolve as resolve10 } from "path";
+import { stat as stat6 } from "fs/promises";
+import { basename as basename15, join as join27, relative as relative5, resolve as resolve10 } from "path";
 var VercelSkillsSourceDriver = class {
   name = "vercel-skills";
   git = new GitSourceDriver();
@@ -6541,7 +7042,7 @@ var VercelSkillsSourceDriver = class {
     const parsed = parseVercelSource(source);
     if (parsed.kind === "local") {
       const resolvedPath = resolve10(parsed.path);
-      if (!await pathExists(resolvedPath) || !(await stat5(resolvedPath)).isDirectory()) {
+      if (!await pathExists(resolvedPath) || !(await stat6(resolvedPath)).isDirectory()) {
         throw new Error(`Vercel skills local source not found: ${resolvedPath}`);
       }
       return {
@@ -6596,7 +7097,7 @@ var VercelSkillsSourceDriver = class {
 };
 async function resolveVercelSkillSubpath(root, subpath) {
   if (!subpath) return root;
-  const candidates = [join26(root, subpath), join26(root, "skills", subpath)];
+  const candidates = [join27(root, subpath), join27(root, "skills", subpath)];
   for (const candidate of candidates) {
     if (await pathExists(candidate)) return candidate;
   }
@@ -6666,14 +7167,14 @@ function getSourceDriver(name = "local") {
 }
 
 // src/staging/staging.ts
-import { chmod, cp as cp5, mkdir as mkdir18, mkdtemp as mkdtemp3, readdir as readdir5, stat as stat8 } from "fs/promises";
-import { basename as basename19, dirname as dirname23, join as join30, relative as relative7, resolve as resolve12, sep as sep2 } from "path";
+import { chmod, cp as cp5, mkdir as mkdir19, mkdtemp as mkdtemp3, readdir as readdir6, stat as stat9 } from "fs/promises";
+import { basename as basename19, dirname as dirname24, join as join31, relative as relative7, resolve as resolve12, sep as sep2 } from "path";
 import { tmpdir as tmpdir4 } from "os";
 
 // src/compose/markdown.ts
-import { createHash as createHash6 } from "crypto";
-import { readdir as readdir3, readFile as readFile20, stat as stat6, writeFile as writeFile17 } from "fs/promises";
-import { basename as basename16, dirname as dirname20, extname as extname3, join as join27, relative as relative6, resolve as resolve11, sep } from "path";
+import { createHash as createHash7 } from "crypto";
+import { readdir as readdir4, readFile as readFile21, stat as stat7, writeFile as writeFile17 } from "fs/promises";
+import { basename as basename16, dirname as dirname21, extname as extname3, join as join28, relative as relative6, resolve as resolve11, sep } from "path";
 var includePattern = /<!--\s*openpack:include(\?)?\s+([^>]+?)\s*-->/g;
 var escapedIncludePattern = /<!--\s*openpack\\:include(\?)?\s+([^>]+?)\s*-->/g;
 var generatedPattern = /<!--\s*(?:BEGIN|END)\s+openpack:include\b/;
@@ -6711,7 +7212,7 @@ async function validateMarkdownIncludes(artifacts, packageRoot, options = {}) {
   }
 }
 async function expandFile(file, packageRoot, appendEntries, artifactPaths, options) {
-  const raw = await readFile20(file, "utf8");
+  const raw = await readFile21(file, "utf8");
   const owner = ownerSelector(packageRoot, file, options.nodeId);
   const expanded = await expandContent(raw, packageRoot, [owner], artifactPaths, options);
   let content = expanded.content;
@@ -6800,11 +7301,11 @@ async function expandInclude(selector, packageRoot, artifactPaths, options) {
     if (options.optional) return void 0;
     throw new Error(`OpenPack include not found: ${displaySelector}`);
   }
-  const stats = await stat6(sourcePath);
+  const stats = await stat7(sourcePath);
   if (!stats.isFile()) {
     throw new Error(`OpenPack include is not a file: ${displaySelector}`);
   }
-  const raw = sourceContent ?? await readFile20(sourcePath, "utf8");
+  const raw = sourceContent ?? await readFile21(sourcePath, "utf8");
   const { optional: _optional, markers: _markers, chain: _chain, ...childOptions } = options;
   const expanded = await expandContent(raw, includePackageRoot, [...options.chain, displaySelector], includeArtifactPaths, {
     ...childOptions,
@@ -6871,7 +7372,7 @@ function resolvePackageSelector(packageRoot, selector) {
 }
 async function markdownFilesForArtifact(artifact) {
   const root = artifact.stagedPath ?? artifact.sourcePath;
-  const stats = await stat6(root);
+  const stats = await stat7(root);
   if (stats.isFile()) return extname3(root).toLowerCase() === ".md" ? [root] : [];
   if (!stats.isDirectory()) return [];
   return listMarkdownFiles(root);
@@ -6879,8 +7380,8 @@ async function markdownFilesForArtifact(artifact) {
 async function listMarkdownFiles(root) {
   const out = [];
   async function walk2(dir) {
-    for (const entry of (await readdir3(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
-      const full = join27(dir, entry.name);
+    for (const entry of (await readdir4(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join28(dir, entry.name);
       if (entry.isDirectory()) {
         await walk2(full);
       } else if (entry.isFile() && extname3(entry.name).toLowerCase() === ".md") {
@@ -6894,7 +7395,7 @@ async function listMarkdownFiles(root) {
 function composeEntriesForFile(artifact, file) {
   if (!artifact.compose?.length) return [];
   if (artifact.kind === "file") return [resolve11(artifact.stagedPath ?? artifact.sourcePath), resolve11(file)].every(Boolean) && resolve11(artifact.stagedPath ?? artifact.sourcePath) === resolve11(file) ? artifact.compose : [];
-  return basename16(file) === "SKILL.md" && dirname20(file) === resolve11(artifact.stagedPath ?? artifact.sourcePath) ? artifact.compose : [];
+  return basename16(file) === "SKILL.md" && dirname21(file) === resolve11(artifact.stagedPath ?? artifact.sourcePath) ? artifact.compose : [];
 }
 function orderedForExpansion(artifacts) {
   return [...artifacts].sort((a, b) => Number(a.type === "fragments") - Number(b.type === "fragments"));
@@ -6925,7 +7426,7 @@ function cleanSelector(value) {
   return value.trim().replace(/\s+/g, " ");
 }
 function sha256(content) {
-  return createHash6("sha256").update(content).digest("hex");
+  return createHash7("sha256").update(content).digest("hex");
 }
 function uniqueComposedFrom(entries) {
   if (entries.length === 0) return [];
@@ -6940,8 +7441,8 @@ function artifactPathMap(artifacts) {
 }
 
 // src/staging/customize.ts
-import { cp as cp4, mkdir as mkdir16, readdir as readdir4, readFile as readFile21, writeFile as writeFile18 } from "fs/promises";
-import { dirname as dirname21, join as join28 } from "path";
+import { cp as cp4, mkdir as mkdir17, readdir as readdir5, readFile as readFile22, writeFile as writeFile18 } from "fs/promises";
+import { dirname as dirname22, join as join29 } from "path";
 async function applyCustomizations(artifacts, options) {
   let next = [...artifacts];
   next = await applyReplacements2(next, options, "override", installableArtifactTypes());
@@ -6957,15 +7458,15 @@ async function applyFragmentCustomizations(artifacts, options) {
   return next.sort((a, b) => `${a.type}:${a.name}:${a.channel}`.localeCompare(`${b.type}:${b.name}:${b.channel}`));
 }
 async function applyInstructionOverlay(artifacts, options) {
-  const overlayPath = join28(options.workspaceRoot, ".agentwheel", "overlays", options.adapter.name, "instructions.local.md");
+  const overlayPath = join29(options.workspaceRoot, ".agentwheel", "overlays", options.adapter.name, "instructions.local.md");
   if (!await pathExists(overlayPath)) return artifacts;
   const index = artifacts.findIndex((artifact2) => artifact2.type === "instructions");
   if (index < 0) return artifacts;
   const artifact = artifacts[index];
-  const managed = await readFile21(artifact.stagedPath ?? artifact.sourcePath, "utf8");
-  const local = await readFile21(overlayPath, "utf8");
-  const composedPath = join28(options.stageRoot, ".agentwheel-composed", "instructions", "AGENTS.md");
-  await mkdir16(dirname21(composedPath), { recursive: true });
+  const managed = await readFile22(artifact.stagedPath ?? artifact.sourcePath, "utf8");
+  const local = await readFile22(overlayPath, "utf8");
+  const composedPath = join29(options.stageRoot, ".agentwheel-composed", "instructions", "AGENTS.md");
+  await mkdir17(dirname22(composedPath), { recursive: true });
   await writeFile18(
     composedPath,
     [
@@ -6992,19 +7493,19 @@ async function applyInstructionOverlay(artifacts, options) {
   return [...artifacts.slice(0, index), updated, ...artifacts.slice(index + 1)];
 }
 async function applyAdditions(artifacts, options) {
-  const additionsRoot = join28(options.workspaceRoot, ".agentwheel", "additions");
-  const rulesRoot = join28(additionsRoot, "rules");
+  const additionsRoot = join29(options.workspaceRoot, ".agentwheel", "additions");
+  const rulesRoot = join29(additionsRoot, "rules");
   if (!await pathExists(rulesRoot)) return artifacts;
   const additions = [];
   for (const entry of await sortedDirEntries2(rulesRoot)) {
-    const full = join28(rulesRoot, entry.name);
+    const full = join29(rulesRoot, entry.name);
     if (!entry.isFile()) continue;
     additions.push({
       type: "rules",
       name: entry.name,
       sourcePath: full,
       stagedPath: full,
-      relativePath: join28("additions", "rules", entry.name),
+      relativePath: join29("additions", "rules", entry.name),
       kind: "file",
       hash: await hashPath(full),
       packageName: options.packageName,
@@ -7028,17 +7529,17 @@ async function applyReplacements2(artifacts, options, channel, artifactTypes) {
       );
     }
     for (const type of artifactTypes) {
-      const typeRoot = join28(root, type);
+      const typeRoot = join29(root, type);
       if (!await pathExists(typeRoot)) continue;
       for (const entry of await sortedDirEntries2(typeRoot)) {
         const artifactMapKey = `${type}:${entry.name}`;
         if (seen.has(artifactMapKey)) continue;
         seen.add(artifactMapKey);
-        const full = join28(typeRoot, entry.name);
+        const full = join29(typeRoot, entry.name);
         const artifactKind = entry.isDirectory() ? "dir" : "file";
         const existing = byKey.get(artifactMapKey);
-        const stagedPath = join28(options.stageRoot, ".agentwheel-composed", channel, type, entry.name);
-        await mkdir16(dirname21(stagedPath), { recursive: true });
+        const stagedPath = join29(options.stageRoot, ".agentwheel-composed", channel, type, entry.name);
+        await mkdir17(dirname22(stagedPath), { recursive: true });
         await cp4(full, stagedPath, { recursive: artifactKind === "dir", dereference: true });
         byKey.set(artifactMapKey, {
           ...existing,
@@ -7046,7 +7547,7 @@ async function applyReplacements2(artifacts, options, channel, artifactTypes) {
           name: entry.name,
           sourcePath: full,
           stagedPath,
-          relativePath: existing?.relativePath ?? join28(type, entry.name),
+          relativePath: existing?.relativePath ?? join29(type, entry.name),
           kind: artifactKind,
           hash: await hashPath(stagedPath),
           packageName,
@@ -7061,13 +7562,13 @@ function replacementRoots(options, channel) {
   const stateDir = channel === "override" ? "overrides" : "ejected";
   const roots = [];
   if (options.graphNodeId) {
-    roots.push({ root: join28(options.workspaceRoot, ".agentwheel", stateDir, ...options.graphNodeId.split("/")), kind: "node" });
+    roots.push({ root: join29(options.workspaceRoot, ".agentwheel", stateDir, ...options.graphNodeId.split("/")), kind: "node" });
   }
   if (options.packageName && options.packageVersion) {
-    roots.push({ root: join28(options.workspaceRoot, ".agentwheel", stateDir, ...`${options.packageName}@${options.packageVersion}`.split("/")), kind: "version" });
+    roots.push({ root: join29(options.workspaceRoot, ".agentwheel", stateDir, ...`${options.packageName}@${options.packageVersion}`.split("/")), kind: "version" });
   }
   if (options.packageName) {
-    roots.push({ root: join28(options.workspaceRoot, ".agentwheel", stateDir, ...options.packageName.split("/")), kind: "package" });
+    roots.push({ root: join29(options.workspaceRoot, ".agentwheel", stateDir, ...options.packageName.split("/")), kind: "package" });
   }
   return roots;
 }
@@ -7078,12 +7579,12 @@ function installableArtifactTypes() {
   return ["instructions", "rules", "skills", "commands", "subagents", "mcp", "hooks", "settings", "plugins"];
 }
 async function sortedDirEntries2(path) {
-  return (await readdir4(path, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+  return (await readdir5(path, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
 }
 
 // src/staging/claude-subagents.ts
-import { mkdir as mkdir17, readFile as readFile22, writeFile as writeFile19 } from "fs/promises";
-import { basename as basename18, dirname as dirname22, join as join29 } from "path";
+import { mkdir as mkdir18, readFile as readFile23, writeFile as writeFile19 } from "fs/promises";
+import { basename as basename18, dirname as dirname23, join as join30 } from "path";
 async function renderClaudeSubagents(artifacts, stageRoot, adapter) {
   if (adapter?.name !== "claude") return artifacts;
   const names = /* @__PURE__ */ new Set();
@@ -7105,16 +7606,16 @@ async function renderClaudeSubagents(artifacts, stageRoot, adapter) {
 async function renderClaudeSubagent(artifact, stageRoot) {
   const sourcePath = artifact.stagedPath ?? artifact.sourcePath;
   const agentName = claudeAgentName(artifact);
-  const markdownPath = artifact.kind === "dir" ? join29(sourcePath, "AGENTS.md") : sourcePath;
+  const markdownPath = artifact.kind === "dir" ? join30(sourcePath, "AGENTS.md") : sourcePath;
   if (artifact.kind === "dir" && !await pathExists(markdownPath)) {
     throw new Error(`Claude subagent directory ${artifact.relativePath} must contain AGENTS.md.`);
   }
   if (artifact.kind === "file" && !artifact.name.toLowerCase().endsWith(".md") && !sourcePath.toLowerCase().endsWith(".md")) {
     throw new Error(`Claude subagent ${artifact.relativePath} must be a .md file or directory containing AGENTS.md.`);
   }
-  const content = await readFile22(markdownPath, "utf8");
-  const renderedPath = join29(stageRoot, ".agentwheel-rendered", "claude-subagents", `${agentName}.md`);
-  await mkdir17(dirname22(renderedPath), { recursive: true });
+  const content = await readFile23(markdownPath, "utf8");
+  const renderedPath = join30(stageRoot, ".agentwheel-rendered", "claude-subagents", `${agentName}.md`);
+  await mkdir18(dirname23(renderedPath), { recursive: true });
   await writeFile19(renderedPath, content.endsWith("\n") ? content : `${content}
 `, "utf8");
   return {
@@ -7122,7 +7623,7 @@ async function renderClaudeSubagent(artifact, stageRoot) {
     name: `${agentName}.md`,
     sourcePath: renderedPath,
     stagedPath: renderedPath,
-    relativePath: join29("subagents", `${agentName}.md`),
+    relativePath: join30("subagents", `${agentName}.md`),
     kind: "file",
     hash: await hashPath(renderedPath)
   };
@@ -7138,18 +7639,23 @@ async function stageSource(driver, source, options = {}) {
 }
 async function stageSourceRaw(driver, source, options = {}) {
   const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(source, options))));
-  return stageResolvedSourceRaw(driver, resolved);
+  try {
+    const staged = await stageResolvedSourceRaw(driver, resolved);
+    return { ...staged, source: { ...staged.source, cacheLeasePath: void 0 } };
+  } finally {
+    await releaseGitSnapshotLease(resolved.cacheLeasePath);
+  }
 }
 async function stageResolvedSourceRaw(driver, resolved) {
   const artifacts = await driver.list(resolved);
   return stageResolvedArtifactsRaw(resolved, artifacts);
 }
 async function stageResolvedArtifactsRaw(resolved, artifacts) {
-  const root = await mkdtemp3(join30(tmpdir4(), "agentwheel-stage-"));
+  const root = await mkdtemp3(join31(tmpdir4(), "agentwheel-stage-"));
   const stagedArtifacts = [];
   for (const artifact of artifacts) {
-    const stagedPath = join30(root, artifact.relativePath);
-    await mkdir18(dirname23(stagedPath), { recursive: true });
+    const stagedPath = join31(root, artifact.relativePath);
+    await mkdir19(dirname24(stagedPath), { recursive: true });
     await cp5(artifact.sourcePath, stagedPath, {
       recursive: artifact.kind === "dir",
       dereference: true,
@@ -7206,6 +7712,7 @@ async function renderStagedBundle(bundle, options = {}) {
       mode: resolved.mode ?? "pinned",
       requestedRef: resolved.requestedRef,
       resolvedCommit: resolved.resolvedCommit,
+      cacheIdentity: resolved.cacheIdentity,
       sourceHash: resolved.sourceHash,
       generatedAt,
       artifacts: finalArtifacts.map((artifact) => ({
@@ -7236,16 +7743,16 @@ async function composeAssets(artifact, packageRoot, stagedPath) {
   }
   for (const asset of artifact.assets) {
     const source = resolvePackagePath(packageRoot, asset.from);
-    const dest = join30(stagedPath, asset.into);
+    const dest = join31(stagedPath, asset.into);
     await copyAsset(asset, source, dest);
   }
 }
 async function copyAsset(asset, source, dest) {
-  const sourceStats = await stat8(source);
+  const sourceStats = await stat9(source);
   if (sourceStats.isFile()) {
     if (matchesAny(basename19(source), asset.include)) {
-      await mkdir18(dest, { recursive: true });
-      await copyAssetFile(source, join30(dest, basename19(source)), asset);
+      await mkdir19(dest, { recursive: true });
+      await copyAssetFile(source, join31(dest, basename19(source)), asset);
     }
     return;
   }
@@ -7253,7 +7760,7 @@ async function copyAsset(asset, source, dest) {
     throw new Error(`Asset include source is not a file or directory: ${source}`);
   }
   if (!asset.include?.length) {
-    await mkdir18(dirname23(dest), { recursive: true });
+    await mkdir19(dirname24(dest), { recursive: true });
     await cp5(source, dest, { recursive: true, dereference: true });
     if (asset.mode === "copy") await normalizeCopiedModes(dest);
     return;
@@ -7261,11 +7768,11 @@ async function copyAsset(asset, source, dest) {
   for (const file of await listFiles(source)) {
     const rel = relative7(source, file).replaceAll("\\", "/");
     if (!matchesAny(rel, asset.include) && !matchesAny(basename19(file), asset.include)) continue;
-    await copyAssetFile(file, join30(dest, rel), asset);
+    await copyAssetFile(file, join31(dest, rel), asset);
   }
 }
 async function copyAssetFile(source, dest, asset) {
-  await mkdir18(dirname23(dest), { recursive: true });
+  await mkdir19(dirname24(dest), { recursive: true });
   await cp5(source, dest, { dereference: true });
   if (asset.mode === "copy") await chmod(dest, 420);
 }
@@ -7280,8 +7787,8 @@ function resolvePackagePath(packageRoot, path) {
 async function listFiles(root) {
   const out = [];
   async function walk2(dir) {
-    for (const entry of (await readdir5(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
-      const full = join30(dir, entry.name);
+    for (const entry of (await readdir6(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join31(dir, entry.name);
       if (entry.isDirectory()) {
         await walk2(full);
       } else if (entry.isFile()) {
@@ -7293,14 +7800,14 @@ async function listFiles(root) {
   return out;
 }
 async function normalizeCopiedModes(path) {
-  const stats = await stat8(path);
+  const stats = await stat9(path);
   if (stats.isFile()) {
     await chmod(path, 420);
     return;
   }
   if (!stats.isDirectory()) return;
-  for (const entry of await readdir5(path, { withFileTypes: true })) {
-    await normalizeCopiedModes(join30(path, entry.name));
+  for (const entry of await readdir6(path, { withFileTypes: true })) {
+    await normalizeCopiedModes(join31(path, entry.name));
   }
 }
 function matchesAny(path, patterns) {
@@ -7313,10 +7820,10 @@ function matchesGlob(path, pattern) {
 }
 
 // src/model/workspace.ts
-import { readFile as readFile23 } from "fs/promises";
+import { readFile as readFile24 } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import { dirname as dirname24, join as join31, resolve as resolve13 } from "path";
-import { z as z6 } from "zod";
+import { dirname as dirname25, join as join32, resolve as resolve13 } from "path";
+import { z as z7 } from "zod";
 
 // src/resolve/semver.ts
 var semverPattern = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
@@ -7415,14 +7922,14 @@ function compareSemver(a, b) {
 }
 
 // src/model/workspace.ts
-var artifactSelectorListSchema = z6.array(z6.string().min(1));
-var workspaceSelectionImportSchema = z6.object({
-  export: z6.string().min(1),
+var artifactSelectorListSchema = z7.array(z7.string().min(1));
+var workspaceSelectionImportSchema = z7.object({
+  export: z7.string().min(1),
   add: artifactSelectorListSchema.optional(),
   exclude: artifactSelectorListSchema.optional()
 }).strict();
-var workspaceSelectionExportSchema = z6.object({
-  extends: z6.string().min(1).optional(),
+var workspaceSelectionExportSchema = z7.object({
+  extends: z7.string().min(1).optional(),
   select: artifactSelectorListSchema.optional(),
   add: artifactSelectorListSchema.optional(),
   exclude: artifactSelectorListSchema.optional()
@@ -7442,29 +7949,29 @@ var workspaceSelectionExportSchema = z6.object({
     });
   }
 });
-var workspaceExportsSchema = z6.object({
-  selections: z6.record(z6.string().min(1), workspaceSelectionExportSchema).default({})
+var workspaceExportsSchema = z7.object({
+  selections: z7.record(z7.string().min(1), workspaceSelectionExportSchema).default({})
 }).strict();
-var workspacePackageBaseSchema = z6.object({
-  name: z6.string().min(1),
-  source: z6.string().min(1),
-  driver: z6.enum(["local", "git", "skillkit", "vercel-skills", "mcp-registry", "clawhub"]).default("local"),
-  adapter: z6.string().min(1).default("openclaw"),
-  adapterConfig: z6.string().min(1).optional(),
-  adapterModule: z6.string().min(1).optional(),
-  adapterCodeHash: z6.string().min(16).optional(),
+var workspacePackageBaseSchema = z7.object({
+  name: z7.string().min(1),
+  source: z7.string().min(1),
+  driver: z7.enum(["local", "git", "skillkit", "vercel-skills", "mcp-registry", "clawhub"]).default("local"),
+  adapter: z7.string().min(1).default("openclaw"),
+  adapterConfig: z7.string().min(1).optional(),
+  adapterModule: z7.string().min(1).optional(),
+  adapterCodeHash: z7.string().min(16).optional(),
   installationType: installationTypeSchema.optional(),
-  mode: z6.enum(["pinned", "tracking"]).default("pinned"),
-  version: z6.string().min(1).refine(isSupportedVersionRange, {
+  mode: z7.enum(["pinned", "tracking"]).default("pinned"),
+  version: z7.string().min(1).refine(isSupportedVersionRange, {
     message: "Version policy must be an exact semver, ~range, ^range, comparator range, or *"
   }).optional(),
-  requestedRef: z6.string().min(1).optional(),
-  select: z6.array(z6.string().min(1)).optional(),
-  skills: z6.array(z6.string().min(1)).optional(),
-  withSuggestions: z6.boolean().optional(),
-  suggestions: z6.array(z6.string().min(1)).optional(),
-  aliases: z6.record(z6.string(), z6.string().min(1)).optional(),
-  overrides: z6.array(z6.string().min(1)).optional()
+  requestedRef: z7.string().min(1).optional(),
+  select: z7.array(z7.string().min(1)).optional(),
+  skills: z7.array(z7.string().min(1)).optional(),
+  withSuggestions: z7.boolean().optional(),
+  suggestions: z7.array(z7.string().min(1)).optional(),
+  aliases: z7.record(z7.string(), z7.string().min(1)).optional(),
+  overrides: z7.array(z7.string().min(1)).optional()
 });
 var workspacePackageSchema = workspacePackageBaseSchema.extend({
   selection: workspaceSelectionImportSchema.optional()
@@ -7478,31 +7985,33 @@ var workspacePackageSchema = workspacePackageBaseSchema.extend({
   }
 });
 var workspacePackageV1Schema = workspacePackageBaseSchema.extend({
-  selection: z6.never().optional()
+  selection: z7.never().optional()
 });
-var commandSchema = z6.array(z6.string().min(1)).min(1);
-var commandListSchema = z6.array(commandSchema).min(1).optional();
-var workspaceProfileRuntimeSchema = z6.object({
-  agent: z6.string().min(1).optional(),
-  adapter: z6.string().min(1).default("openclaw"),
-  adapterConfig: z6.string().min(1).optional(),
-  adapterModule: z6.string().min(1).optional(),
+var commandSchema = z7.array(z7.string().min(1)).min(1);
+var commandListSchema = z7.array(commandSchema).min(1).optional();
+var installStateKeySchema = z7.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i);
+var workspaceProfileRuntimeSchema = z7.object({
+  agent: z7.string().min(1).optional(),
+  adapter: z7.string().min(1).default("openclaw"),
+  adapterConfig: z7.string().min(1).optional(),
+  adapterModule: z7.string().min(1).optional(),
   installationType: installationTypeSchema.optional(),
-  targetRoot: z6.string().min(1).optional(),
-  executePlugins: z6.boolean().optional(),
-  reloadRuntimes: z6.boolean().optional(),
+  stateKey: installStateKeySchema.optional(),
+  targetRoot: z7.string().min(1).optional(),
+  executePlugins: z7.boolean().optional(),
+  reloadRuntimes: z7.boolean().optional(),
   reloadCommands: commandListSchema
 });
-var workspaceProfileMemberSchema = z6.object({
-  id: z6.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i),
-  workspace: z6.string().min(1),
-  profile: z6.string().min(1),
-  transport: z6.enum(["local", "ssh"]).default("local"),
-  host: z6.string().min(1).optional(),
-  user: z6.string().min(1).optional(),
-  port: z6.number().int().positive().optional(),
-  identityFile: z6.string().min(1).optional(),
-  refreshTtlSeconds: z6.number().int().positive().optional()
+var workspaceProfileMemberSchema = z7.object({
+  id: z7.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i),
+  workspace: z7.string().min(1),
+  profile: z7.string().min(1),
+  transport: z7.enum(["local", "ssh"]).default("local"),
+  host: z7.string().min(1).optional(),
+  user: z7.string().min(1).optional(),
+  port: z7.number().int().positive().optional(),
+  identityFile: z7.string().min(1).optional(),
+  refreshTtlSeconds: z7.number().int().positive().optional()
 }).strict().superRefine((member, ctx) => {
   if (member.transport === "ssh" && !member.host) {
     ctx.addIssue({ code: "custom", path: ["host"], message: "SSH profile members require host" });
@@ -7511,14 +8020,14 @@ var workspaceProfileMemberSchema = z6.object({
     ctx.addIssue({ code: "custom", path: ["workspace"], message: "SSH profile member workspaces must be absolute" });
   }
 });
-var workspaceLeafProfileSchema = z6.object({
-  runtimes: z6.array(workspaceProfileRuntimeSchema).min(1),
-  members: z6.never().optional()
+var workspaceLeafProfileSchema = z7.object({
+  runtimes: z7.array(workspaceProfileRuntimeSchema).min(1),
+  members: z7.never().optional()
 }).strict();
-var workspaceCompositeProfileSchema = z6.object({
-  members: z6.array(workspaceProfileMemberSchema).min(1),
-  runtimes: z6.never().optional(),
-  refreshTtlSeconds: z6.number().int().positive().default(86400)
+var workspaceCompositeProfileSchema = z7.object({
+  members: z7.array(workspaceProfileMemberSchema).min(1),
+  runtimes: z7.never().optional(),
+  refreshTtlSeconds: z7.number().int().positive().default(86400)
 }).strict().superRefine((profile, ctx) => {
   const seen = /* @__PURE__ */ new Set();
   for (const [index, member] of profile.members.entries()) {
@@ -7528,31 +8037,32 @@ var workspaceCompositeProfileSchema = z6.object({
     seen.add(member.id);
   }
 });
-var workspaceProfileSchema = z6.union([
+var workspaceProfileSchema = z7.union([
   workspaceLeafProfileSchema,
   workspaceCompositeProfileSchema
 ]);
-var workspaceRegistrySchema = z6.object({
-  sources: z6.array(z6.string().min(1)).optional(),
-  ttlSeconds: z6.number().int().positive().optional()
+var workspaceRegistrySchema = z7.object({
+  sources: z7.array(z7.string().min(1)).optional(),
+  ttlSeconds: z7.number().int().positive().optional()
 }).default({});
-var workspaceTrustSchema = z6.object({
-  allow: z6.array(z6.string().min(1)).optional(),
-  acceptedSources: z6.array(z6.string().min(1)).optional(),
-  denyArtifactTypes: z6.array(artifactTypeSchema).optional(),
-  requireReviewForTransitive: z6.boolean().optional()
+var workspaceTrustSchema = z7.object({
+  allow: z7.array(z7.string().min(1)).optional(),
+  acceptedSources: z7.array(z7.string().min(1)).optional(),
+  denyArtifactTypes: z7.array(artifactTypeSchema).optional(),
+  requireReviewForTransitive: z7.boolean().optional()
 }).default({});
-var workspaceAgentSchema = z6.object({
-  adapter: z6.string().min(1),
-  adapterConfig: z6.string().min(1).optional(),
-  adapterModule: z6.string().min(1).optional(),
-  root: z6.string().min(1),
+var workspaceAgentSchema = z7.object({
+  adapter: z7.string().min(1),
+  adapterConfig: z7.string().min(1).optional(),
+  adapterModule: z7.string().min(1).optional(),
+  root: z7.string().min(1),
   installationType: installationTypeSchema.optional(),
-  transport: z6.enum(["local", "ssh"]).default("local"),
-  host: z6.string().min(1).optional(),
-  user: z6.string().min(1).optional(),
-  port: z6.number().int().positive().optional(),
-  identityFile: z6.string().min(1).optional(),
+  stateKey: installStateKeySchema.optional(),
+  transport: z7.enum(["local", "ssh"]).default("local"),
+  host: z7.string().min(1).optional(),
+  user: z7.string().min(1).optional(),
+  port: z7.number().int().positive().optional(),
+  identityFile: z7.string().min(1).optional(),
   reloadCommands: commandListSchema
 }).superRefine((agent, ctx) => {
   if (agent.transport !== "ssh") return;
@@ -7564,34 +8074,34 @@ var workspaceAgentSchema = z6.object({
     });
   }
 });
-var workspaceConfigBaseSchema = z6.object({
-  bootstrapSkills: z6.boolean().optional(),
+var workspaceConfigBaseSchema = z7.object({
+  bootstrapSkills: z7.boolean().optional(),
   registry: workspaceRegistrySchema,
   trust: workspaceTrustSchema,
-  profiles: z6.record(z6.string(), workspaceProfileSchema).default({}),
-  agents: z6.record(z6.string(), workspaceAgentSchema).default({})
+  profiles: z7.record(z7.string(), workspaceProfileSchema).default({}),
+  agents: z7.record(z7.string(), workspaceAgentSchema).default({})
 });
 var workspaceConfigV1Schema = workspaceConfigBaseSchema.extend({
-  schemaVersion: z6.literal(1),
-  packages: z6.array(workspacePackageV1Schema).default([]),
-  exports: z6.never().optional()
+  schemaVersion: z7.literal(1),
+  packages: z7.array(workspacePackageV1Schema).default([]),
+  exports: z7.never().optional()
 });
 var workspaceConfigV2Schema = workspaceConfigBaseSchema.extend({
-  schemaVersion: z6.literal(2),
-  packages: z6.array(workspacePackageSchema).default([]),
+  schemaVersion: z7.literal(2),
+  packages: z7.array(workspacePackageSchema).default([]),
   exports: workspaceExportsSchema.default({ selections: {} })
 });
-var workspaceConfigSchema = z6.discriminatedUnion("schemaVersion", [
+var workspaceConfigSchema = z7.discriminatedUnion("schemaVersion", [
   workspaceConfigV1Schema,
   workspaceConfigV2Schema
 ]);
 function workspaceConfigPath(workspaceRoot) {
-  return join31(workspaceRoot, ".agentwheel", "config.json");
+  return join32(workspaceRoot, ".agentwheel", "config.json");
 }
 async function readWorkspaceConfig(workspaceRoot) {
   const path = workspaceConfigPath(workspaceRoot);
   if (!await pathExists(path)) return emptyWorkspaceConfig();
-  return workspaceConfigSchema.parse(JSON.parse(await readFile23(path, "utf8")));
+  return workspaceConfigSchema.parse(JSON.parse(await readFile24(path, "utf8")));
 }
 async function writeWorkspaceConfig(workspaceRoot, config) {
   await writeJsonAtomic(workspaceConfigPath(workspaceRoot), workspaceConfigSchema.parse(config));
@@ -7604,13 +8114,13 @@ function upsertPackage(config, entry) {
   return workspaceConfigSchema.parse({ ...parsed, packages });
 }
 function globalWorkspaceConfigPath(globalRoot = homedir5()) {
-  return join31(globalRoot, ".agentwheel", "config.json");
+  return join32(globalRoot, ".agentwheel", "config.json");
 }
 async function findWorkspaceRoot(start = process.cwd()) {
   let current = resolve13(start);
   while (true) {
     if (await pathExists(workspaceConfigPath(current))) return current;
-    const parent = dirname24(current);
+    const parent = dirname25(current);
     if (parent === current) return resolve13(start);
     current = parent;
   }
@@ -7652,7 +8162,7 @@ function isCompositeWorkspaceProfile(profile) {
 }
 async function readConfigPath(path) {
   if (!await pathExists(path)) return emptyWorkspaceConfig();
-  return workspaceConfigSchema.parse(JSON.parse(await readFile23(path, "utf8")));
+  return workspaceConfigSchema.parse(JSON.parse(await readFile24(path, "utf8")));
 }
 function mergeWorkspaceTrust(global, project) {
   return {
@@ -7667,21 +8177,21 @@ function sortedUnique2(values) {
 }
 
 // src/lifecycle/customization.ts
-import { appendFile, cp as cp6, mkdir as mkdir19, rm as rm9 } from "fs/promises";
-import { dirname as dirname26, join as join34 } from "path";
+import { appendFile, cp as cp6, mkdir as mkdir20, rm as rm10 } from "fs/promises";
+import { dirname as dirname27, join as join35 } from "path";
 
 // src/resolve/graph.ts
-import { createHash as createHash8 } from "crypto";
-import { mkdtemp as mkdtemp4, readdir as readdir6, readFile as readFile26, stat as stat10 } from "fs/promises";
+import { createHash as createHash9 } from "crypto";
+import { mkdtemp as mkdtemp4, readdir as readdir7, readFile as readFile27, stat as stat11 } from "fs/promises";
 import { tmpdir as tmpdir5 } from "os";
-import { basename as basename20, extname as extname4, join as join33 } from "path";
+import { basename as basename20, extname as extname4, join as join34 } from "path";
 
 // src/model/workspace-composition.ts
-import { createHash as createHash7 } from "crypto";
-import { readFile as readFile24 } from "fs/promises";
-import { z as z7 } from "zod";
-var selectionSourceConfigSchema = z7.object({
-  schemaVersion: z7.literal(2),
+import { createHash as createHash8 } from "crypto";
+import { readFile as readFile25 } from "fs/promises";
+import { z as z8 } from "zod";
+var selectionSourceConfigSchema = z8.object({
+  schemaVersion: z8.literal(2),
   exports: workspaceExportsSchema
 }).passthrough();
 async function resolveSelectionImport(sourceRoot, sourceDriver, selection) {
@@ -7697,7 +8207,7 @@ async function resolveSelectionImport(sourceRoot, sourceDriver, selection) {
   }
   let raw;
   try {
-    raw = JSON.parse(await readFile24(path, "utf8"));
+    raw = JSON.parse(await readFile25(path, "utf8"));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`Selection import '${parsedSelection.export}' cannot parse ${path}: ${message}`);
@@ -7775,7 +8285,7 @@ function sortedUnique3(values) {
   return [...new Set(values)].sort((a, b) => a.localeCompare(b));
 }
 function sha2562(value) {
-  return createHash7("sha256").update(value).digest("hex");
+  return createHash8("sha256").update(value).digest("hex");
 }
 function stableJson(value) {
   return JSON.stringify(stableValue2(value));
@@ -7799,42 +8309,42 @@ import { homedir as homedir7 } from "os";
 import { resolve as resolve15 } from "path";
 
 // src/registry/client.ts
-import { readFile as readFile25, rm as rm8, stat as stat9 } from "fs/promises";
+import { readFile as readFile26, rm as rm9, stat as stat10 } from "fs/promises";
 import { homedir as homedir6 } from "os";
-import { dirname as dirname25, join as join32, resolve as resolve14 } from "path";
+import { dirname as dirname26, join as join33, resolve as resolve14 } from "path";
 import { fileURLToPath } from "url";
 
 // src/model/registry.ts
-import { z as z8 } from "zod";
-var registryEntrySchema = z8.object({
-  name: z8.string().min(1),
-  source: z8.string().min(1),
-  type: z8.enum(["package", "skill", "plugin", "mcp", "adapter"]).default("package"),
-  description: z8.string().default(""),
-  tags: z8.array(z8.string().min(1)).default([]),
-  select: z8.array(z8.string().min(1)).optional(),
-  skills: z8.array(z8.string().min(1)).optional(),
-  homepageUrl: z8.string().min(1).optional(),
-  homepageLinkLabel: z8.string().min(1).optional(),
-  sourceUrl: z8.string().min(1).optional(),
-  sourceLinkLabel: z8.string().min(1).optional(),
-  openpack: z8.object({
-    schemaVersion: z8.number().int().positive().optional(),
-    specVersion: z8.string().min(1).optional()
+import { z as z9 } from "zod";
+var registryEntrySchema = z9.object({
+  name: z9.string().min(1),
+  source: z9.string().min(1),
+  type: z9.enum(["package", "skill", "plugin", "mcp", "adapter"]).default("package"),
+  description: z9.string().default(""),
+  tags: z9.array(z9.string().min(1)).default([]),
+  select: z9.array(z9.string().min(1)).optional(),
+  skills: z9.array(z9.string().min(1)).optional(),
+  homepageUrl: z9.string().min(1).optional(),
+  homepageLinkLabel: z9.string().min(1).optional(),
+  sourceUrl: z9.string().min(1).optional(),
+  sourceLinkLabel: z9.string().min(1).optional(),
+  openpack: z9.object({
+    schemaVersion: z9.number().int().positive().optional(),
+    specVersion: z9.string().min(1).optional()
   }).passthrough().optional()
 });
-var registryIndexSchema = z8.union([
-  z8.array(registryEntrySchema),
-  z8.object({
-    schemaVersion: z8.literal(1).optional(),
-    entries: z8.array(registryEntrySchema)
+var registryIndexSchema = z9.union([
+  z9.array(registryEntrySchema),
+  z9.object({
+    schemaVersion: z9.literal(1).optional(),
+    entries: z9.array(registryEntrySchema)
   })
 ]).transform((value) => Array.isArray(value) ? value : value.entries);
-var registryCacheSchema = z8.object({
-  version: z8.literal(1),
-  fetchedAt: z8.string().datetime(),
-  sources: z8.array(z8.string().min(1)),
-  entries: z8.array(registryEntrySchema)
+var registryCacheSchema = z9.object({
+  version: z9.literal(1),
+  fetchedAt: z9.string().datetime(),
+  sources: z9.array(z9.string().min(1)),
+  entries: z9.array(registryEntrySchema)
 });
 
 // src/registry/client.ts
@@ -7875,7 +8385,7 @@ var RegistryClient = class {
     return index.entries.find((entry) => entry.name === name);
   }
   async clearCache() {
-    await rm8(this.cachePath, { force: true });
+    await rm9(this.cachePath, { force: true });
   }
   async getSources() {
     if (this.options.sources?.length) return this.options.sources;
@@ -7898,7 +8408,7 @@ var RegistryClient = class {
   }
   async readCache() {
     if (!await pathExists(this.cachePath)) return void 0;
-    return registryCacheSchema.parse(JSON.parse(await readFile25(this.cachePath, "utf8")));
+    return registryCacheSchema.parse(JSON.parse(await readFile26(this.cachePath, "utf8")));
   }
   isExpired(cache, ttlMs) {
     return this.now().getTime() - new Date(cache.fetchedAt).getTime() > ttlMs;
@@ -7916,11 +8426,11 @@ var RegistryClient = class {
     const filePath = source.startsWith("file:") ? fileURLToPath(source) : source;
     if (await pathExists(filePath)) {
       const fullPath = resolve14(filePath);
-      const stats = await stat9(fullPath);
-      return readFile25(stats.isDirectory() ? join32(fullPath, "index.json") : fullPath, "utf8");
+      const stats = await stat10(fullPath);
+      return readFile26(stats.isDirectory() ? join33(fullPath, "index.json") : fullPath, "utf8");
     }
-    const resolved = await this.git.fetch(await this.git.resolve(source, { cacheRoot: join32(dirname25(this.cachePath), "registry-repos") }));
-    return readFile25(join32(resolved.resolvedPath, "index.json"), "utf8");
+    const resolved = await this.git.fetch(await this.git.resolve(source, { cacheRoot: join33(dirname26(this.cachePath), "registry-repos") }));
+    return readFile26(join33(resolved.resolvedPath, "index.json"), "utf8");
   }
   warnCompatibility(entries) {
     for (const entry of entries) {
@@ -7934,7 +8444,7 @@ var RegistryClient = class {
   }
 };
 async function resolvePackageSource(source, workspaceRoot, options = {}) {
-  const { isExplicitSource } = await import("./identify-VV7SXUIQ.js");
+  const { isExplicitSource } = await import("./identify-G3TXOHNS.js");
   if (await isExplicitSource(source)) return { source };
   const entry = await new RegistryClient({ workspaceRoot, offline: options.offline, warn: options.warn }).resolve(source);
   if (!entry) {
@@ -7958,7 +8468,7 @@ function mergeIndexes(indexes) {
   return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 function defaultRegistryCachePath() {
-  return join32(homedir6(), ".agentwheel", "registry-cache.json");
+  return join33(homedir6(), ".agentwheel", "registry-cache.json");
 }
 function sameSources(a, b) {
   return a.length === b.length && a.every((source, index) => source === b[index]);
@@ -8122,7 +8632,7 @@ function normalizeLiteralProviderSpec(source, prefix) {
 var cacheLocks = /* @__PURE__ */ new Map();
 async function resolveDependencyGraph(roots, options) {
   if (roots.length === 0) throw new Error("At least one graph root is required.");
-  const graphRoot = await mkdtemp4(join33(tmpdir5(), "agentwheel-graph-"));
+  const graphRoot = await mkdtemp4(join34(tmpdir5(), "agentwheel-graph-"));
   const fetchCache = /* @__PURE__ */ new Map();
   const nodesByKey = /* @__PURE__ */ new Map();
   const rootResults = [];
@@ -8231,12 +8741,13 @@ Run without ${lockLabel === "Offline" ? "--offline" : "--frozen-lock"} first.`
         }
         lockedByReference = void 0;
         normalized = declared;
+        requirement.updateClosure = true;
       }
     }
     const frozen = lockedByReference ?? lockedNodeForRequirement(normalized.normalizedSource, requirement, options, lockLabel);
     let fetched;
     try {
-      fetched = await fetchPackage(normalized, requirement.mode, options, fetchCache, frozen?.requestedRef);
+      fetched = await fetchPackage(normalized, requirement.mode, options, fetchCache, frozen);
     } catch (error) {
       const usingLockedNode = frozen?.node !== void 0;
       if (!options.frozenLock && !options.offline && !usingLockedNode) throw error;
@@ -8271,6 +8782,7 @@ Run without ${lockLabel === "Offline" ? "--offline" : "--frozen-lock"} first.`
           driver: fetched.resolved.driver,
           requestedRef: fetched.resolved.requestedRef,
           resolvedCommit: fetched.resolved.resolvedCommit,
+          cacheIdentity: fetched.resolved.cacheIdentity,
           sourceHash: fetched.sourceHash,
           mode: fetched.resolved.mode ?? requirement.mode,
           requiredBy: [],
@@ -8642,7 +9154,7 @@ async function collectIncludeNeeds(artifact, artifactsByRelativePath) {
     const file = stack.shift();
     if (scanned.has(file)) continue;
     scanned.add(file);
-    const content = await readFile26(file, "utf8");
+    const content = await readFile27(file, "utf8");
     for (const include of extractOpenPackIncludeSelectors(content)) {
       await collectIncludeSelector(include.raw, include.optional, artifactsByRelativePath, scanned, stack, needs);
     }
@@ -8676,7 +9188,7 @@ function requirementTargetsRuntime(runtimes, runtime, label, warn) {
 }
 async function markdownFilesForArtifact2(artifact) {
   const root = artifact.sourcePath;
-  const stats = await stat10(root);
+  const stats = await stat11(root);
   if (stats.isFile()) return extname4(root).toLowerCase() === ".md" ? [root] : [];
   if (!stats.isDirectory()) return [];
   return listMarkdownFiles2(root);
@@ -8684,8 +9196,8 @@ async function markdownFilesForArtifact2(artifact) {
 async function listMarkdownFiles2(root) {
   const out = [];
   async function walk2(dir) {
-    for (const entry of (await readdir6(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
-      const full = join33(dir, entry.name);
+    for (const entry of (await readdir7(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join34(dir, entry.name);
       if (entry.isDirectory()) {
         await walk2(full);
       } else if (entry.isFile() && extname4(entry.name).toLowerCase() === ".md") {
@@ -8712,17 +9224,19 @@ function dependencyTargetsRuntime(runtimes, runtime, nodeId, alias, warn) {
   warn?.(`skip dependency ${nodeId}:${alias} (not targeted: runtimes=[${runtimes.join(",")}])`);
   return false;
 }
-async function fetchPackage(normalized, mode, options, fetchCache, refOverride) {
+async function fetchPackage(normalized, mode, options, fetchCache, frozen) {
   const hardLockedCheckout = options.frozenLock === true || options.offline === true;
-  const key = `${normalized.driver}\0${normalized.normalizedSource}\0${mode}\0${refOverride ?? ""}\0${hardLockedCheckout ? "hard-locked" : "mutable"}`;
+  const refOverride = frozen?.requestedRef;
+  const key = `${normalized.driver}\0${normalized.normalizedSource}\0${mode}\0${refOverride ?? ""}\0${frozen?.cacheIdentity ?? ""}\0${hardLockedCheckout ? "hard-locked" : "mutable"}`;
   const existing = fetchCache.get(key);
   if (existing) return existing;
   const promise = (async () => {
     const driver = getSourceDriver(normalized.driver);
     const resolved = await driver.resolve(normalized.source, {
-      cacheRoot: options.cacheRoot ?? join33(options.workspaceRoot, ".agentwheel", "cache"),
+      cacheRoot: options.cacheRoot ?? join34(options.workspaceRoot, ".agentwheel", "cache"),
       mode,
       ref: refOverride ?? normalized.requestedRef,
+      cacheIdentity: frozen?.cacheIdentity,
       frozenLock: hardLockedCheckout
     });
     const fetched = await withCachePathLock(resolved.resolvedPath, () => driver.fetch(resolved));
@@ -8771,7 +9285,8 @@ function lockedNodeForRequirement(normalizedSource, requirement, options, label)
   const node = matches[0];
   return {
     node,
-    requestedRef: node.driver === "git" ? node.resolvedCommit ?? node.requestedRef : node.requestedRef
+    requestedRef: lockedSourceRef(node),
+    cacheIdentity: node.cacheIdentity
   };
 }
 function lockedNodeForRequirementReference(requirement, options, label) {
@@ -8804,7 +9319,8 @@ function lockedNodeForRequirementReference(requirement, options, label) {
   }
   return {
     node,
-    requestedRef: node.driver === "git" ? node.resolvedCommit ?? node.requestedRef : node.requestedRef
+    requestedRef: lockedSourceRef(node),
+    cacheIdentity: node.cacheIdentity
   };
 }
 function shouldCheckLockedRootSource(requirement) {
@@ -8827,6 +9343,9 @@ function normalizedSourceFromLockedNode(node) {
     requestedRef: node.requestedRef
   };
 }
+function lockedSourceRef(node) {
+  return node.driver === "git" || node.driver === "skillkit" ? node.resolvedCommit ?? node.requestedRef : node.requestedRef;
+}
 function verifyIntegrity(integrity, sourceHash, label) {
   if (!integrity) return;
   const expected = integrity.replace(/^sha256[-:]/i, "");
@@ -8906,7 +9425,7 @@ function detectDirectCollisions(nodes) {
   }
 }
 function graphNodeId(name, version, normalizedSource, resolvedCommit, sourceHash) {
-  const digest = createHash8("sha256").update(normalizedSource).update("\0").update(resolvedCommit ?? sourceHash).digest("hex").slice(0, 12);
+  const digest = createHash9("sha256").update(normalizedSource).update("\0").update(resolvedCommit ?? sourceHash).digest("hex").slice(0, 12);
   return `${name}@${version}+${digest}`;
 }
 function sortedUnique4(values) {
@@ -8927,8 +9446,8 @@ async function mapLimit(items, limit, fn) {
 
 // src/lifecycle/customization.ts
 async function remember(workspaceRoot, runtime, text) {
-  const overlayPath = join34(workspaceRoot, ".agentwheel", "overlays", runtime, "instructions.local.md");
-  await mkdir19(dirname26(overlayPath), { recursive: true });
+  const overlayPath = join35(workspaceRoot, ".agentwheel", "overlays", runtime, "instructions.local.md");
+  await mkdir20(dirname27(overlayPath), { recursive: true });
   await appendFile(overlayPath, `${text.trim()}
 `, "utf8");
   return { overlayPath };
@@ -8951,9 +9470,9 @@ async function ejectArtifact(workspaceRoot, item) {
       throw new Error(`Artifact not found: ${item}`);
     }
     const ejectedIdentity = parsed.packageIdentity === parsed.packageName ? parsed.packageIdentity : candidate.nodeId === parsed.packageIdentity ? candidate.nodeId : `${candidate.packageName}@${candidate.packageVersion}`;
-    const ejectedPath = join34(workspaceRoot, ".agentwheel", "ejected", ...ejectedIdentity.split("/"), parsed.type, parsed.name);
-    await mkdir19(dirname26(ejectedPath), { recursive: true });
-    await rm9(ejectedPath, { recursive: true, force: true });
+    const ejectedPath = join35(workspaceRoot, ".agentwheel", "ejected", ...ejectedIdentity.split("/"), parsed.type, parsed.name);
+    await mkdir20(dirname27(ejectedPath), { recursive: true });
+    await rm10(ejectedPath, { recursive: true, force: true });
     await cp6(artifact.stagedPath ?? artifact.sourcePath, ejectedPath, { recursive: artifact.kind === "dir", dereference: true });
     return {
       ...parsed,
@@ -8964,7 +9483,7 @@ async function ejectArtifact(workspaceRoot, item) {
       ejectedPath
     };
   } finally {
-    await Promise.all(candidates.map((candidate) => rm9(candidate.bundle.root, { recursive: true, force: true })));
+    await Promise.all(candidates.map((candidate) => rm10(candidate.bundle.root, { recursive: true, force: true })));
   }
 }
 function parseEjectItem(item) {
@@ -8994,7 +9513,7 @@ async function stageEjectCandidate(workspaceRoot, pkg) {
   const adapter = pkg.adapterConfig ? await loadAdapterConfig(pkg.adapterConfig) : getAdapter(pkg.adapter);
   const bundle = await stageSource(driver, normalized.source, {
     adapter,
-    cacheRoot: join34(workspaceRoot, ".agentwheel", "cache"),
+    cacheRoot: join35(workspaceRoot, ".agentwheel", "cache"),
     mode: pkg.mode,
     ref: normalized.requestedRef ?? pkg.requestedRef
   });
@@ -9041,12 +9560,12 @@ function ejectCommands(candidates, parsed) {
 }
 
 // src/lifecycle/profile.ts
-import { rm as rm10 } from "fs/promises";
+import { rm as rm11 } from "fs/promises";
 
 // src/lifecycle/source-plan.ts
-import { createHash as createHash10 } from "crypto";
-import { mkdir as mkdir21 } from "fs/promises";
-import { dirname as dirname28, join as join37 } from "path";
+import { createHash as createHash11 } from "crypto";
+import { mkdir as mkdir22 } from "fs/promises";
+import { dirname as dirname29, join as join38 } from "path";
 
 // src/resolve/graph-diff.ts
 function diffGraphLocks(previous, next) {
@@ -9089,7 +9608,7 @@ function diffNodes(previous, next) {
   for (const [key, oldNode] of previousByStable) {
     const newNode = nextByStable.get(key);
     if (!newNode) continue;
-    if (oldNode.id === newNode.id && oldNode.version === newNode.version && oldNode.resolvedCommit === newNode.resolvedCommit && oldNode.sourceHash === newNode.sourceHash) {
+    if (oldNode.id === newNode.id && oldNode.version === newNode.version && oldNode.resolvedCommit === newNode.resolvedCommit && oldNode.cacheIdentity === newNode.cacheIdentity && oldNode.sourceHash === newNode.sourceHash) {
       continue;
     }
     movedOldIds.add(oldNode.id);
@@ -9161,6 +9680,7 @@ function nodeChangeDetails(oldNode, newNode) {
   const details = [];
   if (oldNode.version !== newNode.version) details.push(`version ${oldNode.version} -> ${newNode.version}`);
   if (oldNode.resolvedCommit !== newNode.resolvedCommit) details.push(`commit ${oldNode.resolvedCommit ?? "<none>"} -> ${newNode.resolvedCommit ?? "<none>"}`);
+  if (oldNode.cacheIdentity !== newNode.cacheIdentity) details.push(`cache ${short(oldNode.cacheIdentity ?? "none")} -> ${short(newNode.cacheIdentity ?? "none")}`);
   if (oldNode.sourceHash !== newNode.sourceHash) details.push(`sourceHash ${short(oldNode.sourceHash)} -> ${short(newNode.sourceHash)}`);
   return details.length > 0 ? ` (${details.join(", ")})` : "";
 }
@@ -9207,12 +9727,12 @@ function formatSelectionImport(root) {
 }
 
 // src/resolve/render.ts
-import { createHash as createHash9 } from "crypto";
-import { readFile as readFile27, mkdtemp as mkdtemp5 } from "fs/promises";
+import { createHash as createHash10 } from "crypto";
+import { readFile as readFile28, mkdtemp as mkdtemp5 } from "fs/promises";
 import { tmpdir as tmpdir6 } from "os";
-import { join as join35 } from "path";
+import { join as join36 } from "path";
 async function renderGraphForTarget(graph, targetContext = {}) {
-  const root = await mkdtemp5(join35(tmpdir6(), "agentwheel-render-"));
+  const root = await mkdtemp5(join36(tmpdir6(), "agentwheel-render-"));
   const artifacts = [];
   const stagedNodes = /* @__PURE__ */ new Map();
   const includeEdges = /* @__PURE__ */ new Map();
@@ -9334,7 +9854,7 @@ async function artifactContentMap(artifacts) {
   const out = /* @__PURE__ */ new Map();
   for (const artifact of artifacts) {
     if (artifact.kind !== "file") continue;
-    out.set(artifact.relativePath.replaceAll("\\", "/"), await readFile27(artifact.stagedPath ?? artifact.sourcePath, "utf8"));
+    out.set(artifact.relativePath.replaceAll("\\", "/"), await readFile28(artifact.stagedPath ?? artifact.sourcePath, "utf8"));
   }
   return out;
 }
@@ -9348,7 +9868,7 @@ function filterArtifactsByRuntime2(artifacts, adapterName, selectedSet) {
   });
 }
 function sha2563(content) {
-  return createHash9("sha256").update(content).digest("hex");
+  return createHash10("sha256").update(content).digest("hex");
 }
 function assignInstallNames(graph, artifacts) {
   const aliases = workspaceAliases(graph);
@@ -9597,13 +10117,13 @@ function lockArtifactFor(artifact) {
 }
 
 // src/lifecycle/trust.ts
-import { mkdir as mkdir20, readFile as readFile28 } from "fs/promises";
+import { mkdir as mkdir21, readFile as readFile29 } from "fs/promises";
 import { homedir as homedir8 } from "os";
-import { dirname as dirname27, join as join36 } from "path";
-import { z as z9 } from "zod";
-var trustStoreSchema = z9.object({
-  version: z9.literal(1),
-  acceptedSources: z9.array(z9.string().min(1)).default([])
+import { dirname as dirname28, join as join37 } from "path";
+import { z as z10 } from "zod";
+var trustStoreSchema = z10.object({
+  version: z10.literal(1),
+  acceptedSources: z10.array(z10.string().min(1)).default([])
 });
 function normalizeTrustPolicy(policy) {
   return {
@@ -9673,14 +10193,14 @@ function sortedUnique5(values) {
 }
 async function readTrustStore(path) {
   if (!await pathExists(path)) return { version: 1, acceptedSources: [] };
-  return trustStoreSchema.parse(JSON.parse(await readFile28(path, "utf8")));
+  return trustStoreSchema.parse(JSON.parse(await readFile29(path, "utf8")));
 }
 async function writeTrustStore(path, store) {
-  await mkdir20(dirname27(path), { recursive: true });
+  await mkdir21(dirname28(path), { recursive: true });
   await writeJsonAtomic(path, trustStoreSchema.parse(store));
 }
 function defaultTrustStorePath() {
-  return process.env.AGENTWHEEL_TRUST_STORE ?? join36(homedir8(), ".agentwheel", "trust.json");
+  return process.env.AGENTWHEEL_TRUST_STORE ?? join37(homedir8(), ".agentwheel", "trust.json");
 }
 
 // src/lifecycle/ownership.ts
@@ -9817,6 +10337,82 @@ function assertManifestIdentity(manifest, request) {
   }
 }
 
+// src/lifecycle/mcp-retirement.ts
+async function createExactMcpRetirementPlan(desiredArtifacts, adapter, targetRoot, manifest, transport = localTransport, options) {
+  if (desiredArtifacts.length !== 1 || desiredArtifacts[0]?.type !== "mcp") {
+    throw new Error(`Exact MCP retirement requires exactly one MCP artifact; found ${desiredArtifacts.length}.`);
+  }
+  if (manifest && manifest.version !== 2) {
+    throw new Error("Exact MCP retirement requires an Agentwheel v2 install manifest when managed state exists.");
+  }
+  if (manifest && manifest.entries.length !== 1) {
+    throw new Error(`Exact MCP retirement requires exactly one manifest entry; found ${manifest.entries.length}.`);
+  }
+  if (options.expectedFromWorkspaceOwner && !manifest) {
+    throw new Error(`Expected managed MCP ownership from ${options.expectedFromWorkspaceOwner}, but no manifest exists.`);
+  }
+  if (options.expectedFromWorkspaceOwner === options.workspaceOwner) {
+    throw new Error("Exact MCP retirement ownership handoff requires different old and new workspace owners.");
+  }
+  const adoption = await createCombinedInstallPlan(
+    desiredArtifacts,
+    adapter,
+    targetRoot,
+    void 0,
+    transport,
+    {
+      baseRevision: manifest?.revision ?? null,
+      graphLockDigest: options.graphLockDigest,
+      workspaceOwner: options.workspaceOwner,
+      installationType: options.installationType,
+      stateKey: options.stateKey,
+      forceConflict: true
+    }
+  );
+  if (adoption.operations.length !== 1) {
+    throw new Error(`Exact MCP retirement expected one rendered operation; found ${adoption.operations.length}.`);
+  }
+  const operation = adoption.operations[0];
+  if (adoption.hasBlockingChanges || operation.action !== "skip" || !operation.mergeStrategy || !operation.mergeRemoval) {
+    return adoption;
+  }
+  if (operation.mergeStrategy !== "json-deep" && operation.mergeStrategy !== "codex-toml-mcp") {
+    throw new Error(`Exact MCP retirement does not support merge strategy ${operation.mergeStrategy}.`);
+  }
+  const removalKeys = Object.keys(operation.mergeRemoval);
+  const servers = operation.mergeRemoval.mcpServers;
+  if (removalKeys.length !== 1 || removalKeys[0] !== "mcpServers" || !servers || typeof servers !== "object" || Array.isArray(servers) || Object.keys(servers).length !== 1) {
+    throw new Error("Exact MCP retirement requires exactly one MCP server and no non-MCP configuration.");
+  }
+  const entry = manifest?.entries[0];
+  if (entry) {
+    const mismatches = [];
+    if (entry.artifactType !== operation.artifactType) mismatches.push(`artifact type ${entry.artifactType}`);
+    if (entry.artifactName !== operation.artifactName) mismatches.push(`artifact name ${entry.artifactName}`);
+    if (entry.path !== operation.relativeDestPath) mismatches.push(`path ${entry.path}`);
+    if (entry.sourceHash !== operation.desiredHash) mismatches.push("source hash");
+    if (entry.mergeStrategy !== operation.mergeStrategy) mismatches.push(`merge strategy ${entry.mergeStrategy ?? "missing"}`);
+    if (entry.mergeCreatedDestination === true) mismatches.push("manifest claims ownership of the whole destination");
+    const expectedOwner = options.expectedFromWorkspaceOwner ?? options.workspaceOwner;
+    if (entry.workspaceOwner !== expectedOwner) mismatches.push(`owner ${entry.workspaceOwner}`);
+    if (mismatches.length > 0) {
+      throw new Error(`Exact MCP retirement manifest precondition failed: ${mismatches.join(", ")}.`);
+    }
+  }
+  return {
+    ...adoption,
+    baseRevision: manifest?.revision ?? null,
+    operations: [{
+      ...operation,
+      action: "remove",
+      exactMergeRemoval: true,
+      manifestHash: entry?.hash,
+      workspaceOwner: options.workspaceOwner,
+      reason: entry ? `retire exact MCP contribution after explicit ownership handoff from ${entry.workspaceOwner}` : `retire exact unmanaged MCP contribution under ${options.workspaceOwner}`
+    }]
+  };
+}
+
 // src/lifecycle/source-plan.ts
 async function createGraphSourcePlan(options) {
   if (options.roots.length === 0) {
@@ -9852,7 +10448,7 @@ async function createGraphSourcePlan(options) {
   const registryClient = new RegistryClient({ workspaceRoot, offline: lockMode, offlineLabel: lockLabel, warn });
   const graph = await resolveDependencyGraph(options.roots, {
     workspaceRoot,
-    cacheRoot: join37(workspaceRoot, ".agentwheel", "cache"),
+    cacheRoot: join38(workspaceRoot, ".agentwheel", "cache"),
     registryClient,
     noDeps: options.noDeps,
     includeSuggestions: options.includeSuggestions,
@@ -9889,10 +10485,24 @@ async function createGraphSourcePlan(options) {
   const graphLockDigest = digestGraphLock(bundle.graphLock);
   const graphDiff = diffGraphLocks(previousLock, bundle.graphLock);
   const manifest = await readInstallManifest(resolvedInstallRoot, options.adapter.name, transport, { installationType: resolvedInstallationType, stateKey });
-  const plan = await createCombinedInstallPlan(desiredArtifacts, options.adapter, options.targetRoot, manifest, transport, {
+  const workspaceOwner = workspaceOwnerForRoot(workspaceRoot);
+  const plan = options.retireExactMcp ? await createExactMcpRetirementPlan(
+    desiredArtifacts,
+    options.adapter,
+    options.targetRoot,
+    manifest,
+    transport,
+    {
+      installationType: resolvedInstallationType,
+      stateKey,
+      workspaceOwner,
+      expectedFromWorkspaceOwner: options.expectedFromWorkspaceOwner,
+      graphLockDigest
+    }
+  ) : await createCombinedInstallPlan(desiredArtifacts, options.adapter, options.targetRoot, manifest, transport, {
     baseRevision: manifest?.revision ?? null,
     graphLockDigest,
-    workspaceOwner: workspaceOwnerForRoot(workspaceRoot),
+    workspaceOwner,
     installationType: resolvedInstallationType,
     stateKey,
     forceDrift: options.forceDrift,
@@ -9958,13 +10568,13 @@ async function readExistingGraphLock(path) {
   return readGraphLock(path);
 }
 function pathForGraphLock(workspaceRoot, targetKey2, adapter, targetFingerprint) {
-  return join37(workspaceRoot, ".agentwheel", "locks", sanitizePathSegment(targetKey2), sanitizePathSegment(adapter), `${targetFingerprint}.graph-lock.json`);
+  return join38(workspaceRoot, ".agentwheel", "locks", sanitizePathSegment(targetKey2), sanitizePathSegment(adapter), `${targetFingerprint}.graph-lock.json`);
 }
 function sanitizePathSegment(value) {
   return value.replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "default";
 }
 function digestGraphLock(lock) {
-  return createHash10("sha256").update(canonicalGraphLockJson(lock)).digest("hex");
+  return createHash11("sha256").update(canonicalGraphLockJson(lock)).digest("hex");
 }
 function assertFrozenGraph(previousLock, graph, frozen, label) {
   if (!frozen) return;
@@ -10090,7 +10700,7 @@ function targetLabel(target) {
 }
 
 // src/runtime/target.ts
-import { basename as basename21, dirname as dirname29, join as join38, resolve as resolve17 } from "path";
+import { basename as basename21, dirname as dirname30, join as join39, resolve as resolve17 } from "path";
 var runtimeMarkers = [
   { adapter: "openclaw", dirs: [".openclaw", ".clawdbot", ".moltbot"] },
   { adapter: "claude", dirs: [".claude"] },
@@ -10161,6 +10771,7 @@ function resolveProfileRuntimeTarget(runtime, config, workspaceRoot, installatio
       ...target,
       adapterConfig: runtime.adapterConfig,
       adapterModule: runtime.adapterModule,
+      stateKey: runtime.stateKey ?? target.stateKey,
       executePlugins: runtime.executePlugins,
       reloadRuntimes: runtime.reloadRuntimes,
       reloadCommands: runtime.reloadCommands ?? target.reloadCommands,
@@ -10173,6 +10784,7 @@ function resolveProfileRuntimeTarget(runtime, config, workspaceRoot, installatio
     adapterConfig: runtime.adapterConfig,
     adapterModule: runtime.adapterModule,
     installationType: installationType ?? runtime.installationType,
+    stateKey: runtime.stateKey,
     targetRoot: runtime.targetRoot ? resolveConfigPath(runtime.targetRoot, workspaceRoot) : workspaceRoot,
     workspaceRoot,
     executePlugins: runtime.executePlugins,
@@ -10211,8 +10823,8 @@ async function detectRuntimeTargets(cwd = process.cwd(), adapterFilter) {
     if (adapterFilter && marker.adapter !== adapterFilter) continue;
     for (const dir of marker.dirs) {
       if (basename21(root) === dir) {
-        matches.push({ adapter: marker.adapter, targetRoot: dirname29(root) });
-      } else if (await pathExists(join38(root, dir))) {
+        matches.push({ adapter: marker.adapter, targetRoot: dirname30(root) });
+      } else if (await pathExists(join39(root, dir))) {
         matches.push({ adapter: marker.adapter, targetRoot: root });
       }
     }
@@ -10231,6 +10843,7 @@ function targetFromAgent(name, config, workspaceRoot, installationType) {
     adapterConfig: agent.adapterConfig,
     adapterModule: agent.adapterModule,
     installationType: installationType ?? agent.installationType,
+    stateKey: agent.stateKey,
     targetRoot: agent.transport === "ssh" ? agent.root : resolveConfigPath(agent.root, workspaceRoot),
     workspaceRoot,
     reloadCommands: agent.reloadCommands,
@@ -10254,7 +10867,7 @@ function dedupeTargets(matches) {
 function runtimeScanRoot(request) {
   const root = resolve17(request.targetRoot ?? request.cwd ?? process.cwd());
   if (request.targetRoot) return root;
-  return runtimeMarkers.some((marker) => marker.dirs.includes(basename21(root))) ? dirname29(root) : root;
+  return runtimeMarkers.some((marker) => marker.dirs.includes(basename21(root))) ? dirname30(root) : root;
 }
 
 // src/lifecycle/profile.ts
@@ -10317,9 +10930,11 @@ async function syncProfile(options) {
         agentName: target.agentName,
         targetRoot: target.targetRoot,
         transport: transport.kind,
-        ssh: target.ssh
+        ssh: target.ssh,
+        stateKey: target.stateKey
       },
       installationType,
+      stateKey: target.stateKey,
       noDeps: options.noDeps,
       includeSuggestions: options.includeSuggestions,
       suggestionAliases: options.suggestionAliases,
@@ -10362,7 +10977,7 @@ async function syncProfile(options) {
       }
       results.push(result);
     } finally {
-      await rm10(graphPlan.bundle.root, { recursive: true, force: true });
+      await rm11(graphPlan.bundle.root, { recursive: true, force: true });
     }
   }
   return results;
@@ -10556,9 +11171,9 @@ function shellQuoteArg(value) {
 }
 
 // src/cli/update-check.ts
-import { mkdir as mkdir22, readFile as readFile29, writeFile as writeFile20 } from "fs/promises";
+import { mkdir as mkdir23, readFile as readFile30, writeFile as writeFile20 } from "fs/promises";
 import { homedir as homedir9 } from "os";
-import { dirname as dirname30, join as join39 } from "path";
+import { dirname as dirname31, join as join40 } from "path";
 var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
 var DEFAULT_TIMEOUT_MS = 300;
 var REGISTRY_URL = "https://registry.npmjs.org/agentwheel";
@@ -10566,7 +11181,7 @@ async function maybeCheckForUpdate(options) {
   if (isDisabled(options)) return;
   const now = options.now?.() ?? /* @__PURE__ */ new Date();
   const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
-  const cachePath = options.cachePath ?? join39(homedir9(), ".agentwheel", "update-check.json");
+  const cachePath = options.cachePath ?? join40(homedir9(), ".agentwheel", "update-check.json");
   try {
     const cached = await readCache(cachePath);
     if (cached && now.getTime() - Date.parse(cached.checkedAt) < ttlMs) {
@@ -10603,7 +11218,7 @@ async function fetchLatestVersion(fetchImpl, timeoutMs) {
 }
 async function readCache(path) {
   try {
-    const parsed = JSON.parse(await readFile29(path, "utf8"));
+    const parsed = JSON.parse(await readFile30(path, "utf8"));
     if (typeof parsed.checkedAt !== "string" || typeof parsed.latest !== "string") return void 0;
     return { checkedAt: parsed.checkedAt, latest: parsed.latest };
   } catch {
@@ -10611,7 +11226,7 @@ async function readCache(path) {
   }
 }
 async function writeCache(path, cache) {
-  await mkdir22(dirname30(path), { recursive: true });
+  await mkdir23(dirname31(path), { recursive: true });
   await writeFile20(path, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
@@ -10634,7 +11249,7 @@ function normalizeVersion(version) {
 }
 
 // src/model/package-validate.ts
-import { stat as stat11 } from "fs/promises";
+import { stat as stat12 } from "fs/promises";
 import { resolve as resolve18 } from "path";
 async function validatePackage(root) {
   const packageRoot = resolve18(root);
@@ -10727,7 +11342,7 @@ async function validateManifestComposeInclude(packageRoot, selector, optional, f
       findings.push({ level: "error", message: `Compose include escapes package root: ${selector}`, path: manifestPath });
       return;
     }
-    if (!optional) await stat11(full);
+    if (!optional) await stat12(full);
   } catch (error) {
     if (!optional) {
       findings.push({ level: "error", message: error instanceof Error ? error.message : String(error), path: manifestPath });
@@ -10775,13 +11390,13 @@ function isCrossPackageSelector(value) {
 }
 
 // src/model/package-migrate.ts
-import { readFile as readFile30, rename as rename4, writeFile as writeFile21 } from "fs/promises";
-import { join as join41, resolve as resolve19 } from "path";
+import { readFile as readFile31, rename as rename5, writeFile as writeFile21 } from "fs/promises";
+import { join as join42, resolve as resolve19 } from "path";
 import { applyEdits, modify, parse as parse5 } from "jsonc-parser";
 async function migratePackageManifest(root) {
   const packageRoot = resolve19(root);
   for (const name of openPackManifestNames) {
-    const path = join41(packageRoot, name);
+    const path = join42(packageRoot, name);
     if (await pathExists(path)) {
       return { changed: false, to: path, message: `Package already uses ${name}.` };
     }
@@ -10790,18 +11405,18 @@ async function migratePackageManifest(root) {
   if (!legacyName) {
     throw new Error(`No legacy package manifest found at ${packageRoot}`);
   }
-  const from = join41(packageRoot, legacyName);
+  const from = join42(packageRoot, legacyName);
   const toName = legacyName.endsWith(".jsonc") ? "openpack.jsonc" : "openpack.json";
-  const to = join41(packageRoot, toName);
-  const content = await readFile30(from, "utf8");
+  const to = join42(packageRoot, toName);
+  const content = await readFile31(from, "utf8");
   const updated = updateSchemaVersion(content);
-  await rename4(from, to);
+  await rename5(from, to);
   await writeFile21(to, updated, "utf8");
   return { changed: true, from, to, message: `Migrated ${legacyName} to ${toName}.` };
 }
 async function firstExistingLegacyManifest(root) {
   for (const name of legacyPackageManifestNames) {
-    if (await pathExists(join41(root, name))) return name;
+    if (await pathExists(join42(root, name))) return name;
   }
   return void 0;
 }
@@ -10819,45 +11434,45 @@ function updateSchemaVersion(content) {
 
 // src/cli/version.ts
 import { readFileSync } from "fs";
-import { dirname as dirname31, join as join42 } from "path";
+import { dirname as dirname32, join as join43 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var FALLBACK_VERSION = "0.0.0";
 function resolveCliVersion() {
-  let dir = dirname31(fileURLToPath2(import.meta.url));
+  let dir = dirname32(fileURLToPath2(import.meta.url));
   while (true) {
     try {
-      const pkg = JSON.parse(readFileSync(join42(dir, "package.json"), "utf8"));
+      const pkg = JSON.parse(readFileSync(join43(dir, "package.json"), "utf8"));
       if (pkg.name === "agentwheel" && typeof pkg.version === "string") {
         return pkg.version;
       }
     } catch {
     }
-    const parent = dirname31(dir);
+    const parent = dirname32(dir);
     if (parent === dir) return FALLBACK_VERSION;
     dir = parent;
   }
 }
 
 // src/version/policy.ts
-import { execFile as execFile5 } from "child_process";
-import { readFile as readFile31 } from "fs/promises";
-import { join as join43, resolve as resolve20 } from "path";
-import { promisify as promisify5 } from "util";
+import { execFile as execFile6 } from "child_process";
+import { readFile as readFile32 } from "fs/promises";
+import { join as join44, resolve as resolve20 } from "path";
+import { promisify as promisify6 } from "util";
 import { parse as parseJsonc } from "jsonc-parser";
-import { z as z10 } from "zod";
-var execFileAsync5 = promisify5(execFile5);
+import { z as z11 } from "zod";
+var execFileAsync6 = promisify6(execFile6);
 var DEFAULT_VERSION_REFRESH_TTL_SECONDS = 86400;
-var cachedVersionSchema = z10.object({
-  version: z10.string().min(1),
-  ref: z10.string().min(1)
+var cachedVersionSchema = z11.object({
+  version: z11.string().min(1),
+  ref: z11.string().min(1)
 });
-var versionCacheEntrySchema = z10.object({
-  checkedAt: z10.string().datetime(),
-  versions: z10.array(cachedVersionSchema)
+var versionCacheEntrySchema = z11.object({
+  checkedAt: z11.string().datetime(),
+  versions: z11.array(cachedVersionSchema)
 });
-var versionCacheSchema = z10.object({
-  schemaVersion: z10.literal(1),
-  sources: z10.record(z10.string(), versionCacheEntrySchema)
+var versionCacheSchema = z11.object({
+  schemaVersion: z11.literal(1),
+  sources: z11.record(z11.string(), versionCacheEntrySchema)
 });
 async function discoverPackageVersions(pkg, workspaceRoot, options = {}) {
   const now = (options.now ?? (() => /* @__PURE__ */ new Date()))();
@@ -10939,7 +11554,7 @@ async function discoverVersionsFromSource(pkg, workspaceRoot) {
     const manifest2 = await readPackageManifest(root);
     const current = manifest2 ? [{ version: manifest2.version, ref: pkg.requestedRef ?? root }] : [];
     try {
-      const { stdout } = await execFileAsync5("git", ["-C", root, "remote", "get-url", "origin"]);
+      const { stdout } = await execFileAsync6("git", ["-C", root, "remote", "get-url", "origin"]);
       return uniqueVersions([
         ...await discoverGitTagsFromUrl(stdout.trim(), pkg.version, root),
         ...current
@@ -10950,7 +11565,7 @@ async function discoverVersionsFromSource(pkg, workspaceRoot) {
   }
   const driver = getSourceDriver(driverName);
   const resolved = await driver.resolve(pkg.source, {
-    cacheRoot: join43(workspaceRoot, ".agentwheel", "cache"),
+    cacheRoot: join44(workspaceRoot, ".agentwheel", "cache"),
     mode: "tracking",
     ref: pkg.requestedRef
   });
@@ -10965,7 +11580,7 @@ async function discoverGitTags(source, policy) {
   return discoverGitTagsFromUrl(url, policy, localRoot);
 }
 async function discoverGitTagsFromUrl(url, policy, localRoot) {
-  const { stdout } = await execFileAsync5("git", ["ls-remote", "--tags", "--refs", url], {
+  const { stdout } = await execFileAsync6("git", ["ls-remote", "--tags", "--refs", url], {
     maxBuffer: 10 * 1024 * 1024
   });
   const byVersion = /* @__PURE__ */ new Map();
@@ -11003,7 +11618,7 @@ async function manifestVersionAtRef(url, ref, localRoot) {
   if (localRoot) {
     for (const name of ["openpack.json", "openpack.jsonc"]) {
       try {
-        const { stdout } = await execFileAsync5("git", ["-C", localRoot, "show", `${ref}:${name}`], {
+        const { stdout } = await execFileAsync6("git", ["-C", localRoot, "show", `${ref}:${name}`], {
           maxBuffer: 1024 * 1024
         });
         const parsed = parseJsonc(stdout);
@@ -11044,27 +11659,27 @@ function gitUrlFromSource(source) {
   throw new Error(`Version discovery does not support Git source: ${source}`);
 }
 function versionCachePath(workspaceRoot) {
-  return join43(workspaceRoot, ".agentwheel", "cache", "version-index.json");
+  return join44(workspaceRoot, ".agentwheel", "cache", "version-index.json");
 }
 async function readVersionCache(path) {
   if (!await pathExists(path)) return { schemaVersion: 1, sources: {} };
   try {
-    return versionCacheSchema.parse(JSON.parse(await readFile31(path, "utf8")));
+    return versionCacheSchema.parse(JSON.parse(await readFile32(path, "utf8")));
   } catch {
     return { schemaVersion: 1, sources: {} };
   }
 }
 
 // src/profile/members.ts
-import { execFile as execFile6 } from "child_process";
-import { readFile as readFile32 } from "fs/promises";
-import { join as join44, resolve as resolve21 } from "path";
-import { promisify as promisify6 } from "util";
-import { z as z12 } from "zod";
+import { execFile as execFile7 } from "child_process";
+import { readFile as readFile33 } from "fs/promises";
+import { join as join45, resolve as resolve21 } from "path";
+import { promisify as promisify7 } from "util";
+import { z as z13 } from "zod";
 
 // src/status/report.ts
-import { z as z11 } from "zod";
-var statusHealthSchema = z11.enum([
+import { z as z12 } from "zod";
+var statusHealthSchema = z12.enum([
   "PASS",
   "WARN",
   "FAIL",
@@ -11073,77 +11688,77 @@ var statusHealthSchema = z11.enum([
   "INCOMPATIBLE",
   "BUSY"
 ]);
-var statusPackageSchema = z11.object({
-  name: z11.string().min(1),
-  source: z11.string().min(1),
-  mode: z11.enum(["pinned", "tracking"]),
-  policy: z11.string().min(1),
-  installed: z11.string().nullable(),
-  locked: z11.string().nullable(),
-  latestAllowed: z11.string().nullable(),
-  latestOverall: z11.string().nullable(),
-  availability: z11.enum(["FRESH", "STALE", "UNKNOWN"]),
-  checkedAt: z11.string().nullable(),
-  error: z11.string().optional(),
-  updateAvailableAllowed: z11.boolean(),
-  updateAvailableOverall: z11.boolean()
+var statusPackageSchema = z12.object({
+  name: z12.string().min(1),
+  source: z12.string().min(1),
+  mode: z12.enum(["pinned", "tracking"]),
+  policy: z12.string().min(1),
+  installed: z12.string().nullable(),
+  locked: z12.string().nullable(),
+  latestAllowed: z12.string().nullable(),
+  latestOverall: z12.string().nullable(),
+  availability: z12.enum(["FRESH", "STALE", "UNKNOWN"]),
+  checkedAt: z12.string().nullable(),
+  error: z12.string().optional(),
+  updateAvailableAllowed: z12.boolean(),
+  updateAvailableOverall: z12.boolean()
 });
-var statusArtifactSchema = z11.object({
-  selector: z11.string().min(1),
-  type: z11.string().min(1),
-  name: z11.string().min(1),
-  installName: z11.string().min(1),
-  packageName: z11.string().nullable(),
-  packageVersion: z11.string().nullable(),
-  hash: z11.string().min(16),
-  installed: z11.boolean()
+var statusArtifactSchema = z12.object({
+  selector: z12.string().min(1),
+  type: z12.string().min(1),
+  name: z12.string().min(1),
+  installName: z12.string().min(1),
+  packageName: z12.string().nullable(),
+  packageVersion: z12.string().nullable(),
+  hash: z12.string().min(16),
+  installed: z12.boolean()
 });
-var statusTargetSchema = z11.object({
-  adapter: z11.string().min(1),
-  installationType: z11.string().min(1),
-  targetRoot: z11.string().min(1),
+var statusTargetSchema = z12.object({
+  adapter: z12.string().min(1),
+  installationType: z12.string().min(1),
+  targetRoot: z12.string().min(1),
   health: statusHealthSchema,
-  manifestRevision: z11.string().nullable(),
-  manifestEntryCount: z11.number().int().nonnegative(),
-  graphLockPath: z11.string().nullable(),
-  packageCount: z11.number().int().nonnegative(),
-  artifactCount: z11.number().int().nonnegative(),
-  pendingCount: z11.number().int().nonnegative(),
-  driftCount: z11.number().int().nonnegative(),
-  conflictCount: z11.number().int().nonnegative(),
-  error: z11.string().optional(),
-  packages: z11.array(statusPackageSchema),
-  artifacts: z11.array(statusArtifactSchema)
+  manifestRevision: z12.string().nullable(),
+  manifestEntryCount: z12.number().int().nonnegative(),
+  graphLockPath: z12.string().nullable(),
+  packageCount: z12.number().int().nonnegative(),
+  artifactCount: z12.number().int().nonnegative(),
+  pendingCount: z12.number().int().nonnegative(),
+  driftCount: z12.number().int().nonnegative(),
+  conflictCount: z12.number().int().nonnegative(),
+  error: z12.string().optional(),
+  packages: z12.array(statusPackageSchema),
+  artifacts: z12.array(statusArtifactSchema)
 });
-var statusReportSchema = z11.lazy(() => z11.object({
-  schemaVersion: z11.literal(1),
-  command: z11.literal("status"),
-  agentwheelVersion: z11.string().min(1),
-  generatedAt: z11.string().datetime(),
-  workspace: z11.string().min(1),
-  profile: z11.string().nullable(),
+var statusReportSchema = z12.lazy(() => z12.object({
+  schemaVersion: z12.literal(1),
+  command: z12.literal("status"),
+  agentwheelVersion: z12.string().min(1),
+  generatedAt: z12.string().datetime(),
+  workspace: z12.string().min(1),
+  profile: z12.string().nullable(),
   health: statusHealthSchema,
-  repository: z11.object({
-    available: z11.boolean(),
-    branch: z11.string().nullable(),
-    head: z11.string().nullable(),
-    upstream: z11.string().nullable(),
-    ahead: z11.number().int().nonnegative(),
-    behind: z11.number().int().nonnegative(),
-    dirtyCount: z11.number().int().nonnegative(),
-    error: z11.string().optional()
+  repository: z12.object({
+    available: z12.boolean(),
+    branch: z12.string().nullable(),
+    head: z12.string().nullable(),
+    upstream: z12.string().nullable(),
+    ahead: z12.number().int().nonnegative(),
+    behind: z12.number().int().nonnegative(),
+    dirtyCount: z12.number().int().nonnegative(),
+    error: z12.string().optional()
   }),
-  targets: z11.array(statusTargetSchema),
-  members: z11.array(z11.object({
-    id: z11.string().min(1),
-    transport: z11.enum(["local", "ssh"]),
-    workspace: z11.string().min(1),
-    profile: z11.string().min(1),
+  targets: z12.array(statusTargetSchema),
+  members: z12.array(z12.object({
+    id: z12.string().min(1),
+    transport: z12.enum(["local", "ssh"]),
+    workspace: z12.string().min(1),
+    profile: z12.string().min(1),
     health: statusHealthSchema,
-    agentwheelVersion: z11.string().nullable(),
-    checkedAt: z11.string().nullable(),
-    stale: z11.boolean(),
-    error: z11.string().optional(),
+    agentwheelVersion: z12.string().nullable(),
+    checkedAt: z12.string().nullable(),
+    stale: z12.boolean(),
+    error: z12.string().optional(),
     report: statusReportSchema.optional()
   }))
 }));
@@ -11167,10 +11782,10 @@ function blocksCompositeApply(health) {
 }
 
 // src/profile/members.ts
-var execFileAsync6 = promisify6(execFile6);
-var memberCacheSchema = z12.object({
-  schemaVersion: z12.literal(1),
-  checkedAt: z12.string().datetime(),
+var execFileAsync7 = promisify7(execFile7);
+var memberCacheSchema = z13.object({
+  schemaVersion: z13.literal(1),
+  checkedAt: z13.string().datetime(),
   report: statusReportSchema
 });
 async function collectCompositeMembers(options) {
@@ -11234,7 +11849,7 @@ async function invokeMemberStatus(member, parentWorkspace, chain, options, cliEn
   try {
     if (member.transport === "local") {
       const workspace = resolve21(parentWorkspace, member.workspace);
-      const result = await execFileAsync6(process.execPath, [cliEntry, ...args], {
+      const result = await execFileAsync7(process.execPath, [cliEntry, ...args], {
         cwd: workspace,
         env: env2,
         maxBuffer: 20 * 1024 * 1024
@@ -11250,7 +11865,7 @@ async function invokeMemberStatus(member, parentWorkspace, chain, options, cliEn
         "agentwheel",
         ...args.map(shellQuote2)
       ];
-      const result = await execFileAsync6("ssh", [...sshArgs, remoteArgs.join(" ")], {
+      const result = await execFileAsync7("ssh", [...sshArgs, remoteArgs.join(" ")], {
         env: env2,
         maxBuffer: 20 * 1024 * 1024
       });
@@ -11275,7 +11890,7 @@ async function runMemberAgentwheel(member, parentWorkspace, args, chain) {
   const env2 = { ...process.env, AGENTWHEEL_COMPOSITE_CHAIN: JSON.stringify(chain) };
   try {
     if (member.transport === "local") {
-      const result2 = await execFileAsync6(
+      const result2 = await execFileAsync7(
         process.execPath,
         [process.argv[1], "--no-update-check", ...args],
         {
@@ -11294,7 +11909,7 @@ async function runMemberAgentwheel(member, parentWorkspace, args, chain) {
       "--no-update-check",
       ...args.map(shellQuote2)
     ];
-    const result = await execFileAsync6("ssh", [...sshArguments(member), remoteArgs.join(" ")], {
+    const result = await execFileAsync7("ssh", [...sshArguments(member), remoteArgs.join(" ")], {
       env: env2,
       maxBuffer: 20 * 1024 * 1024
     });
@@ -11354,12 +11969,12 @@ function memberFailure(member, health, error) {
   };
 }
 function memberCachePath(workspaceRoot, profileName, memberId) {
-  return join44(workspaceRoot, ".agentwheel", "cache", "member-status", profileName, `${memberId}.json`);
+  return join45(workspaceRoot, ".agentwheel", "cache", "member-status", profileName, `${memberId}.json`);
 }
 async function readMemberCache(path) {
   if (!await pathExists(path)) return void 0;
   try {
-    return memberCacheSchema.parse(JSON.parse(await readFile32(path, "utf8")));
+    return memberCacheSchema.parse(JSON.parse(await readFile33(path, "utf8")));
   } catch {
     return void 0;
   }
@@ -11368,7 +11983,7 @@ function parseCompositeChain() {
   const value = process.env.AGENTWHEEL_COMPOSITE_CHAIN;
   if (!value) return [];
   try {
-    return z12.array(z12.string()).parse(JSON.parse(value));
+    return z13.array(z13.string()).parse(JSON.parse(value));
   } catch {
     throw new Error("Invalid AGENTWHEEL_COMPOSITE_CHAIN protocol value.");
   }
@@ -11384,12 +11999,12 @@ function compositeKey(workspaceRoot, profileName) {
 }
 
 // src/status/repository.ts
-import { execFile as execFile7 } from "child_process";
-import { promisify as promisify7 } from "util";
-var execFileAsync7 = promisify7(execFile7);
+import { execFile as execFile8 } from "child_process";
+import { promisify as promisify8 } from "util";
+var execFileAsync8 = promisify8(execFile8);
 async function collectRepositoryStatus(workspaceRoot) {
   try {
-    const { stdout } = await execFileAsync7(
+    const { stdout } = await execFileAsync8(
       "git",
       ["-C", workspaceRoot, "status", "--porcelain=v2", "--branch"],
       { maxBuffer: 10 * 1024 * 1024 }
@@ -11427,16 +12042,16 @@ function valueAfter(lines, prefix) {
 }
 
 // src/catalogue/client.ts
-import { createHash as createHash11 } from "crypto";
-import { readFile as readFile33, rm as rm11 } from "fs/promises";
+import { createHash as createHash12 } from "crypto";
+import { readFile as readFile34, rm as rm12 } from "fs/promises";
 import { homedir as homedir10 } from "os";
-import { join as join45 } from "path";
+import { join as join46 } from "path";
 
 // src/model/catalogue.ts
-import { z as z13 } from "zod";
-var searchScopeSchema = z13.enum(["all", "registry", "enriched", "vercel"]);
-var searchTypeSchema = z13.enum(["package", "skill", "plugin", "mcp", "adapter"]);
-var searchEcosystemSchema = z13.enum([
+import { z as z14 } from "zod";
+var searchScopeSchema = z14.enum(["all", "registry", "enriched", "vercel"]);
+var searchTypeSchema = z14.enum(["package", "skill", "plugin", "mcp", "adapter"]);
+var searchEcosystemSchema = z14.enum([
   "official",
   "openpack",
   "mcp-registry",
@@ -11444,13 +12059,13 @@ var searchEcosystemSchema = z13.enum([
   "skillkit",
   "vercel"
 ]);
-var catalogueProvenanceSchema = z13.enum(["registry", "enriched", "vercel"]);
-var installabilitySchema = z13.enum(["registry", "source", "informational"]);
-var nullableString = z13.string().nullable();
-var nullableStringArray = z13.array(z13.string()).nullable();
-var enrichedCatalogueEntrySchema = z13.object({
-  id: z13.string().min(1),
-  name: z13.string().min(1),
+var catalogueProvenanceSchema = z14.enum(["registry", "enriched", "vercel"]);
+var installabilitySchema = z14.enum(["registry", "source", "informational"]);
+var nullableString = z14.string().nullable();
+var nullableStringArray = z14.array(z14.string()).nullable();
+var enrichedCatalogueEntrySchema = z14.object({
+  id: z14.string().min(1),
+  name: z14.string().min(1),
   ecosystem: searchEcosystemSchema.nullable(),
   type: searchTypeSchema.nullable(),
   description: nullableString,
@@ -11460,17 +12075,17 @@ var enrichedCatalogueEntrySchema = z13.object({
   repoUrl: nullableString,
   homepageUrl: nullableString.optional(),
   homepageLinkLabel: nullableString.optional(),
-  stars: z13.number().finite().nullable().optional(),
+  stars: z14.number().finite().nullable().optional(),
   lastPush: nullableString.optional(),
-  archived: z13.boolean().nullable(),
+  archived: z14.boolean().nullable(),
   provides: nullableStringArray,
   version: nullableString,
-  featured: z13.boolean().nullable().optional()
+  featured: z14.boolean().nullable().optional()
 });
-var enrichedCatalogueSchema = z13.object({
-  schemaVersion: z13.literal(1),
-  generatedAt: z13.string().datetime(),
-  entries: z13.array(enrichedCatalogueEntrySchema)
+var enrichedCatalogueSchema = z14.object({
+  schemaVersion: z14.literal(1),
+  generatedAt: z14.string().datetime(),
+  entries: z14.array(enrichedCatalogueEntrySchema)
 }).superRefine((value, context) => {
   const seen = /* @__PURE__ */ new Set();
   value.entries.forEach((entry, index) => {
@@ -11484,17 +12099,17 @@ var enrichedCatalogueSchema = z13.object({
     seen.add(entry.id);
   });
 });
-var vercelCatalogueEntrySchema = z13.object({
-  o: z13.string().min(1),
-  r: z13.string().min(1),
-  s: z13.string().min(1),
-  d: z13.string().nullable().optional()
+var vercelCatalogueEntrySchema = z14.object({
+  o: z14.string().min(1),
+  r: z14.string().min(1),
+  s: z14.string().min(1),
+  d: z14.string().nullable().optional()
 });
-var vercelCatalogueSchema = z13.object({
-  schemaVersion: z13.literal(1),
-  generatedAt: z13.string().datetime(),
-  count: z13.number().int().nonnegative(),
-  entries: z13.array(vercelCatalogueEntrySchema)
+var vercelCatalogueSchema = z14.object({
+  schemaVersion: z14.literal(1),
+  generatedAt: z14.string().datetime(),
+  count: z14.number().int().nonnegative(),
+  entries: z14.array(vercelCatalogueEntrySchema)
 }).superRefine((value, context) => {
   if (value.count !== value.entries.length) {
     context.addIssue({
@@ -11516,53 +12131,53 @@ var vercelCatalogueSchema = z13.object({
     seen.add(id);
   });
 });
-var catalogueCacheSchema = z13.object({
-  version: z13.literal(1),
-  fetchedAt: z13.string().datetime(),
-  sources: z13.tuple([z13.string().url(), z13.string().url()]),
+var catalogueCacheSchema = z14.object({
+  version: z14.literal(1),
+  fetchedAt: z14.string().datetime(),
+  sources: z14.tuple([z14.string().url(), z14.string().url()]),
   enriched: enrichedCatalogueSchema,
   vercel: vercelCatalogueSchema,
-  sourceDigests: z13.object({
-    enriched: z13.string().regex(/^[a-f0-9]{64}$/),
-    vercel: z13.string().regex(/^[a-f0-9]{64}$/)
+  sourceDigests: z14.object({
+    enriched: z14.string().regex(/^[a-f0-9]{64}$/),
+    vercel: z14.string().regex(/^[a-f0-9]{64}$/)
   }).optional()
 });
-var catalogueCacheEnvelopeSchema = z13.object({
-  version: z13.literal(1),
-  fetchedAt: z13.string().datetime(),
-  sources: z13.tuple([z13.string().url(), z13.string().url()]),
-  contentHash: z13.string().regex(/^[a-f0-9]{64}$/).optional(),
-  sourceDigests: z13.object({
-    enriched: z13.string().regex(/^[a-f0-9]{64}$/),
-    vercel: z13.string().regex(/^[a-f0-9]{64}$/)
+var catalogueCacheEnvelopeSchema = z14.object({
+  version: z14.literal(1),
+  fetchedAt: z14.string().datetime(),
+  sources: z14.tuple([z14.string().url(), z14.string().url()]),
+  contentHash: z14.string().regex(/^[a-f0-9]{64}$/).optional(),
+  sourceDigests: z14.object({
+    enriched: z14.string().regex(/^[a-f0-9]{64}$/),
+    vercel: z14.string().regex(/^[a-f0-9]{64}$/)
   }).optional(),
-  enriched: z13.unknown(),
-  vercel: z13.unknown()
+  enriched: z14.unknown(),
+  vercel: z14.unknown()
 });
-var searchResultSchema = z13.object({
-  id: z13.string().min(1),
-  name: z13.string().min(1),
-  description: z13.string(),
+var searchResultSchema = z14.object({
+  id: z14.string().min(1),
+  name: z14.string().min(1),
+  description: z14.string(),
   type: searchTypeSchema,
   ecosystem: searchEcosystemSchema.optional(),
-  tags: z13.array(z13.string()),
-  provides: z13.array(z13.string()),
-  source: z13.string().min(1).optional(),
-  repoUrl: z13.string().min(1).optional(),
-  installCommand: z13.string().min(1).optional(),
+  tags: z14.array(z14.string()),
+  provides: z14.array(z14.string()),
+  source: z14.string().min(1).optional(),
+  repoUrl: z14.string().min(1).optional(),
+  installCommand: z14.string().min(1).optional(),
   installability: installabilitySchema,
-  provenances: z13.array(catalogueProvenanceSchema).min(1),
-  score: z13.number().int().nonnegative(),
-  matchedFields: z13.array(z13.string()),
-  semanticScore: z13.number().finite().optional()
+  provenances: z14.array(catalogueProvenanceSchema).min(1),
+  score: z14.number().int().nonnegative(),
+  matchedFields: z14.array(z14.string()),
+  semanticScore: z14.number().finite().optional()
 });
-var searchResponseSchema = z13.object({
-  schemaVersion: z13.literal(1),
-  query: z13.string(),
+var searchResponseSchema = z14.object({
+  schemaVersion: z14.literal(1),
+  query: z14.string(),
   scope: searchScopeSchema,
-  fromCache: z13.boolean(),
-  searchMode: z13.enum(["lexical", "semantic"]).optional(),
-  results: z13.array(searchResultSchema)
+  fromCache: z14.boolean(),
+  searchMode: z14.enum(["lexical", "semantic"]).optional(),
+  results: z14.array(searchResultSchema)
 });
 
 // src/catalogue/client.ts
@@ -11641,12 +12256,12 @@ var CatalogueClient = class {
     }
   }
   async clearCache() {
-    await rm11(this.cachePath, { force: true });
+    await rm12(this.cachePath, { force: true });
   }
   async readCache() {
     if (!await pathExists(this.cachePath)) return void 0;
     try {
-      const value = JSON.parse(await readFile33(this.cachePath, "utf8"));
+      const value = JSON.parse(await readFile34(this.cachePath, "utf8"));
       const envelope = catalogueCacheEnvelopeSchema.parse(value);
       if (envelope.contentHash) {
         const contentHash = catalogueContentHash(envelope.enriched, envelope.vercel);
@@ -11702,18 +12317,18 @@ var CatalogueClient = class {
     }
     return {
       value: schema.parse(value),
-      digest: createHash11("sha256").update(bytes).digest("hex")
+      digest: createHash12("sha256").update(bytes).digest("hex")
     };
   }
 };
 function defaultCatalogueCachePath() {
-  return join45(homedir10(), ".agentwheel", "catalogue-cache.json");
+  return join46(homedir10(), ".agentwheel", "catalogue-cache.json");
 }
 function sameSources2(a, b) {
   return a.length === b.length && a.every((source, index) => source === b[index]);
 }
 function catalogueContentHash(enriched, vercel) {
-  return createHash11("sha256").update(JSON.stringify({ enriched, vercel })).digest("hex");
+  return createHash12("sha256").update(JSON.stringify({ enriched, vercel })).digest("hex");
 }
 
 // src/search/index.ts
@@ -12075,9 +12690,9 @@ function includesToken(normalizedText, token) {
 }
 
 // src/semantic/index.ts
-import { createHash as createHash12 } from "crypto";
+import { createHash as createHash13 } from "crypto";
 import { homedir as homedir11 } from "os";
-import { join as join46 } from "path";
+import { join as join47 } from "path";
 import { env, pipeline } from "@huggingface/transformers";
 var DEFAULT_SEMANTIC_INDEX_URL = "https://raw.githubusercontent.com/NestDevLab/agentwheel-registry/main/catalogue-semantic-index/gte-v1/";
 var CONTRACT = {
@@ -12165,13 +12780,13 @@ var SemanticSearchClient = class {
     if (!response.ok) throw new Error(`Semantic index file failed (${response.status}): ${descriptor.path}`);
     const bytes = new Uint8Array(await response.arrayBuffer());
     if (bytes.byteLength !== descriptor.bytes) throw new Error(`Semantic index file size does not match: ${descriptor.path}`);
-    const digest = createHash12("sha256").update(bytes).digest("hex");
+    const digest = createHash13("sha256").update(bytes).digest("hex");
     if (digest !== descriptor.sha256) throw new Error(`Semantic index checksum does not match: ${descriptor.path}`);
     return bytes;
   }
 };
 async function embedQuery(query) {
-  env.cacheDir = join46(homedir11(), ".agentwheel", "semantic-models");
+  env.cacheDir = join47(homedir11(), ".agentwheel", "semantic-models");
   const extractor = await pipeline("feature-extraction", CONTRACT.model.id, {
     revision: CONTRACT.model.revision,
     dtype: CONTRACT.model.dtype,
@@ -12255,9 +12870,9 @@ function ensureTrailingSlash(value) {
 }
 
 // src/trial/skill.ts
-import { createHash as createHash13 } from "crypto";
-import { readFile as readFile34, stat as stat12 } from "fs/promises";
-import { join as join47 } from "path";
+import { createHash as createHash14 } from "crypto";
+import { readFile as readFile35, stat as stat13 } from "fs/promises";
+import { join as join48 } from "path";
 import { parse as parseYaml2 } from "yaml";
 var MAX_TRIAL_SKILL_BYTES = 512 * 1024;
 async function createSkillTrial(driver, resolved, selectors) {
@@ -12269,12 +12884,12 @@ async function createSkillTrial(driver, resolved, selectors) {
     throw new Error("Skill trial requires exactly one selected skill. Use --skill <name> or --select skills/<name>.");
   }
   const artifact = skills[0];
-  const path = artifact.kind === "dir" ? join47(artifact.sourcePath, "SKILL.md") : artifact.sourcePath;
-  const info = await stat12(path);
+  const path = artifact.kind === "dir" ? join48(artifact.sourcePath, "SKILL.md") : artifact.sourcePath;
+  const info = await stat13(path);
   if (info.size > MAX_TRIAL_SKILL_BYTES) {
     throw new Error(`Skill trial exceeds the ${MAX_TRIAL_SKILL_BYTES / 1024} KiB content limit.`);
   }
-  const content = await readFile34(path, "utf8");
+  const content = await readFile35(path, "utf8");
   const frontmatter = readSkillFrontmatter(content, artifact);
   return {
     schemaVersion: 1,
@@ -12285,7 +12900,7 @@ async function createSkillTrial(driver, resolved, selectors) {
     skill: {
       name: artifact.name,
       relativePath: artifact.relativePath,
-      sha256: createHash13("sha256").update(content).digest("hex"),
+      sha256: createHash14("sha256").update(content).digest("hex"),
       frontmatter,
       content
     }
@@ -12334,6 +12949,15 @@ program.command("init").description("initialize an agentwheel workspace or packa
   if (bootstrapPackage) console.log("Auto-added the agentwheel bootstrap skill for openclaw.");
   console.log(nextInstallNudge());
 });
+var cacheCommand = program.command("cache").description("inspect and maintain local source caches");
+cacheCommand.command("prune").description("remove old Git source snapshots while preserving locked commits").option("-t, --target-root <path>", "workspace root", process.cwd()).option("--keep <count>", "newest snapshots to retain per source", parsePositiveInteger, 3).option("--apply", "delete the selected snapshots; without this flag only preview", false).action(async (options) => {
+  const targetRoot = normalizeTargetRoot(options.targetRoot);
+  const cacheRoot = join49(targetRoot, ".agentwheel", "cache");
+  const result = await pruneGitCache(cacheRoot, { keepSnapshots: options.keep, dryRun: !options.apply });
+  const verb = options.apply ? "Removed" : "Would remove";
+  for (const path of result.removedPaths) console.log(`${verb} ${path}`);
+  console.log(`${options.apply ? "Pruned" : "Preview"}: ${result.removedPaths.length} snapshots; retained ${result.retainedPaths.length}.`);
+});
 program.command("add").description("add a package to .agentwheel/config.json without touching runtimes").argument("<source>", "package source").option("--driver <driver>", "source driver (local, git, skillkit, vercel-skills, mcp-registry, or clawhub)").option("--adapter <adapter>", "built-in adapter", "openclaw").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "workspace root").option("--mode <mode>", "pinned or tracking", "pinned").option("--version <range>", "root package version policy (exact, ~, ^, or *)").option("--name <name>", "package alias").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots on future installs", false).option("--suggestion <alias>", "include one suggested companion alias on future installs (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "allow this package to replace a colliding artifact (repeatable)", collectOverrideOption, []).action(async (source, options) => {
   const normalizedOptions = normalizeRuntimeScopeOptions(options);
   const targetRoot = normalizeTargetRoot(normalizedOptions.targetRoot ?? process.cwd());
@@ -12346,10 +12970,14 @@ program.command("list").description("list artifacts exposed by a package source"
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const selectedArtifacts = selectedArtifactsFromOptionsOrRegistry(options, resolvedInput.registryEntry);
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
-  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join48(targetRoot, ".agentwheel", "cache") }))));
-  const artifacts = filterArtifactsBySelection(await driver.list(resolved), selectedArtifacts);
-  for (const artifact of artifacts) {
-    console.log(`${artifact.type}	${artifact.name}	${artifact.relativePath}`);
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join49(targetRoot, ".agentwheel", "cache") }))));
+  try {
+    const artifacts = filterArtifactsBySelection(await driver.list(resolved), selectedArtifacts);
+    for (const artifact of artifacts) {
+      console.log(`${artifact.type}	${artifact.name}	${artifact.relativePath}`);
+    }
+  } finally {
+    await releaseGitSnapshotLease(resolved.cacheLeasePath);
   }
 });
 program.command("search").description("search registry and public catalogue artifacts").argument("<query>", "search query").option("--json", "print the versioned search response as JSON", false).option("--scope <scope>", "search scope: all, registry, enriched, or vercel", "all").option("--type <type>", "artifact type: package, skill, plugin, mcp, or adapter").option("--ecosystem <ecosystem>", "ecosystem: official, openpack, mcp-registry, clawhub, skillkit, or vercel").option("--limit <n>", "maximum number of results (1-100)", "20").option("--include-archived", "include archived catalogue entries", false).option("--refresh", "refresh registry and catalogue caches", false).option("--offline", "use compatible local caches without network access", false).option("--semantic", "rank published catalogue entries with the verified semantic index", false).option("-t, --target-root <path>", "workspace root", process.cwd()).action(async (query, options) => {
@@ -12411,42 +13039,50 @@ program.command("try").description("read and validate one skill for the current
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
   const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, {
-    cacheRoot: join48(targetRoot, ".agentwheel", "cache")
+    cacheRoot: join49(targetRoot, ".agentwheel", "cache")
   }))));
-  const trial = await createSkillTrial(driver, resolved, selectedArtifactsFromOptionsOrRegistry(options, resolvedInput.registryEntry));
-  if (options.json) {
-    console.log(JSON.stringify(trial, null, 2));
-    return;
+  try {
+    const trial = await createSkillTrial(driver, resolved, selectedArtifactsFromOptionsOrRegistry(options, resolvedInput.registryEntry));
+    if (options.json) {
+      console.log(JSON.stringify(trial, null, 2));
+      return;
+    }
+    console.log(`Read-only skill trial: ${trial.skill.name}`);
+    console.log(`Source: ${trial.source}`);
+    console.log(`Description: ${trial.skill.frontmatter.description}`);
+    console.log("No configuration or runtime files were changed.");
+    console.log("\n--- SKILL.md ---\n");
+    console.log(trial.skill.content);
+  } finally {
+    await releaseGitSnapshotLease(resolved.cacheLeasePath);
   }
-  console.log(`Read-only skill trial: ${trial.skill.name}`);
-  console.log(`Source: ${trial.source}`);
-  console.log(`Description: ${trial.skill.frontmatter.description}`);
-  console.log("No configuration or runtime files were changed.");
-  console.log("\n--- SKILL.md ---\n");
-  console.log(trial.skill.content);
 });
 program.command("scan").description("scan a package source for validation findings").argument("<source>", "package source").option("--driver <driver>", "source driver").option("-t, --target-root <path>", "workspace root", process.cwd()).action(async (source, options) => {
   const targetRoot = normalizeTargetRoot(options.targetRoot);
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
-  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join48(targetRoot, ".agentwheel", "cache") }))));
-  const result = await driver.scan(resolved);
-  if (result.findings.length === 0) {
-    console.log("Scan ok: no findings");
-  } else {
-    for (const finding of result.findings) {
-      console.log(`${finding.level.toUpperCase()}: ${finding.message}${finding.path ? ` (${finding.path})` : ""}`);
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join49(targetRoot, ".agentwheel", "cache") }))));
+  try {
+    const result = await driver.scan(resolved);
+    if (result.findings.length === 0) {
+      console.log("Scan ok: no findings");
+    } else {
+      for (const finding of result.findings) {
+        console.log(`${finding.level.toUpperCase()}: ${finding.message}${finding.path ? ` (${finding.path})` : ""}`);
+      }
     }
+    if (!result.ok) process.exitCode = 1;
+  } finally {
+    await releaseGitSnapshotLease(resolved.cacheLeasePath);
   }
-  if (!result.ok) process.exitCode = 1;
 });
-program.command("plan").description("preview what install would reconcile without writing").argument("[name-or-source]", "configured package name/source or package source to preview").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--profile <name>", "workspace runtime profile").option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "for source previews, allow the source to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--dry-run", "accepted for symmetry; plan never writes", false).option("--format <fmt>", "output format: human|json|mermaid|html", "human").option("--json", "print the resolved plan as JSON", false).option("--force-drift", "replace drifted managed artifacts during install planning", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "with a source argument, exclude configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
+program.command("plan").description("preview what install would reconcile without writing").argument("[name-or-source]", "configured package name/source or package source to preview").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--profile <name>", "workspace runtime profile").option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "for source previews, allow the source to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--dry-run", "accepted for symmetry; plan never writes", false).option("--format <fmt>", "output format: human|json|mermaid|html", "human").option("--json", "print the resolved plan as JSON", false).option("--force-drift", "replace drifted managed artifacts during install planning", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "exclude unrelated configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
   await runInstallCommand(source, { ...options, dryRun: true }, { apply: false });
 });
-program.command("install").description("install configured packages into runtime targets").argument("[name-or-source]", "configured package name/source or package source to add and install").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "when adding a source, allow it to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--format <fmt>", "output format: human|json|mermaid|html", "human").option("--json", "print the resolved plan as JSON", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--reload-runtimes", "run configured runtime reload commands after executed semantic plugin changes", false).option("--restart-runtimes", "alias for --reload-runtimes", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "with a source argument, exclude configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).addHelpText("after", "\nScoped install never removes files owned only by other configured packages; run a full install to reconcile those removals.\n").action(async (source, options) => {
+program.command("install").description("install configured packages into runtime targets").argument("[name-or-source]", "configured package name/source or package source to add and install").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "when adding a source, allow it to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--format <fmt>", "output format: human|json|mermaid|html", "human").option("--json", "print the resolved plan as JSON", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--reload-runtimes", "run configured runtime reload commands after executed semantic plugin changes", false).option("--restart-runtimes", "alias for --reload-runtimes", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "exclude unrelated configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).addHelpText("after", "\nScoped install never removes files owned only by other configured packages; run a full install to reconcile those removals.\n").action(async (source, options) => {
   await runInstallCommand(source, options, { apply: !options.dryRun });
 });
-program.command("serve").description("serve a read-only live dashboard for the resolved install plan").argument("[name-or-source]", "configured package name/source or package source to preview").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--profile <name>", "workspace runtime profile").option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "for source previews, allow the source to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--force-drift", "replace drifted managed artifacts during install planning", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "with a source argument, exclude configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).option("--bind <addr>", "interface to bind", "127.0.0.1").option("--port <n>", "TCP port (0 selects an ephemeral port)", "8765").option("--interval <seconds>", "background re-render cadence in seconds", "60").option("--once", "render once and skip the background re-render loop", false).action(async (source, options) => {
+program.command("serve").description("serve a read-only live dashboard for the resolved install plan").argument("[name-or-source]", "configured package name/source or package source to preview").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--profile <name>", "workspace runtime profile").option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "for source previews, allow the source to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--force-drift", "replace drifted managed artifacts during install planning", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "exclude unrelated configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).option("--bind <addr>", "interface to bind", "127.0.0.1").option("--port <n>", "TCP port (0 selects an ephemeral port)", "8765").option("--interval <seconds>", "background re-render cadence in seconds", "60").option("--once", "render once and skip the background re-render loop", false).action(async (source, options) => {
   await servePlanDashboard({
     bind: options.bind,
     port: parseServePort(options.port),
@@ -12455,11 +13091,13 @@ program.command("serve").description("serve a read-only live dashboard for the r
     buildReport: () => buildPlanReport(source, options)
   });
 });
-program.command("sync", { hidden: true }).argument("[name-or-source]", "configured package name/source or package source").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "when adding a source, allow it to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--reload-runtimes", "run configured runtime reload commands after executed semantic plugin changes", false).option("--restart-runtimes", "alias for --reload-runtimes", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "with a source argument, exclude configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
+program.command("sync", { hidden: true }).argument("[name-or-source]", "configured package name/source or package source").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--override <source-or-package::type/name>", "when adding a source, allow it to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--reload-runtimes", "run configured runtime reload commands after executed semantic plugin changes", false).option("--restart-runtimes", "alias for --reload-runtimes", false).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "exclude unrelated configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
   console.error("warning: 'agentwheel sync' is deprecated and will be removed in 0.10. Use 'agentwheel install'.");
   await runInstallCommand(source, options, { apply: !options.dryRun });
 });
-program.command("update").description("re-resolve tracking packages, then apply the result").argument("[name]", "configured package name or source to update").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("-t, --target-root <path>", "workspace root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plans without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--reload-runtimes", "run configured runtime reload commands after executed semantic plugin changes", false).option("--restart-runtimes", "alias for --reload-runtimes", false).option("--allow-adapter-code", "allow loading local adapter code from configured packages", false).option("--select <type/name>", "temporarily select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "temporarily select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--dependency <name-or-source>", "update one tracking dependency while keeping unrelated graph nodes locked (repeatable)", collectDependencyOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (name, options) => {
+program.command("update").description("re-resolve tracking packages, then apply the result").argument("[name]", "configured package name or source to update").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("-t, --target-root <path>", "workspace root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plans without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--reload-runtimes", "run configured runtime reload commands after executed semantic plugin changes", false).option("--restart-runtimes", "alias for --reload-runtimes", false).option("--allow-adapter-code", "allow loading local adapter code from configured packages", false).option("--select <type/name>", "temporarily select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "temporarily select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--dependency <name-or-source>", "update one tracking dependency while keeping unrelated graph nodes locked (repeatable)", collectDependencyOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "exclude unrelated configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (name, options) => {
+  if (options.onlySource && options.dependency.length > 0) throw new Error("--only-source cannot be combined with --dependency.");
+  if (options.onlySource && !name) throw new Error("--only-source requires a configured package argument.");
   if (name && options.dependency.length > 0) throw new Error("A package argument cannot be combined with --dependency.");
   if (options.dependency.length > 0 && (options.select.length > 0 || options.skill.length > 0)) {
     throw new Error("--dependency cannot be combined with --select or --skill; package selections remain unchanged.");
@@ -12478,6 +13116,11 @@ program.command("update").description("re-resolve tracking packages, then apply
     await runConfiguredGraphPackages(target, { ...normalizedOptions, scope: name }, { mode: "update" });
   }
 });
+program.command("skill").description("operate on configured skills").addCommand(
+  new Command("update").description("reconcile one skill through its configured owning package").argument("<name>", "configured skill name").option("--package <name>", "owning configured package when automatic ownership is ambiguous").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("-t, --target-root <path>", "workspace root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plans without writing", false).option("--adopt", "replace unmanaged destinations in the owning package closure", false).option("--force-drift", "replace drifted managed artifacts", false).option("--allow-adapter-code", "allow loading local adapter code from the owning package", false).option("--no-deps", "resolve only the owning package and ignore its requires with a warning").option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (name, options) => {
+    await runSkillUpdateCommand(name, options);
+  })
+);
 program.command("deps").description("inspect the OpenPack dependency graph").addCommand(
   new Command("tree").description("print the OpenPack dependency graph").argument("[source]", "optional package source to resolve").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "shortcut for --installation-type user and home-scoped state", false).option("--local", "shortcut for --installation-type local", false).option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
     const normalizedOptions = normalizeRuntimeScopeOptions(options, { defaultUser: shouldDefaultUserInstall(source, options) });
@@ -12492,7 +13135,7 @@ program.command("deps").description("inspect the OpenPack dependency graph").add
           for (const decision of result.bundle.graphLock.canonical.overrides) {
             console.log(`OVERRIDE ${decision.graphNodeId}:${decision.type}/${decision.name} replaces ${decision.overriddenGraphNodeId}:${decision.type}/${decision.name} via ${decision.rootId} (${decision.selector})`);
           }
-          await rm12(result.bundle.root, { recursive: true, force: true });
+          await rm13(result.bundle.root, { recursive: true, force: true });
         }
         continue;
       }
@@ -12621,6 +13264,11 @@ ownershipCommand.command("handoff").description("transfer one managed artifact b
   console.log(`Manifest revision: ${result.manifestRevision}`);
   console.log(`Owner: ${result.fromOwner} -> ${result.toOwner}`);
 });
+var mcpCommand = program.command("mcp").description("operate on MCP runtime configuration");
+mcpCommand.command("retire").description("remove one exact legacy MCP contribution with explicit state ownership").argument("<package>", "configured package containing exactly one legacy MCP artifact").option("--agent <name>", "one named agent from merged config").option("--profile <name>", "workspace runtime profile resolving to one target").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--from-workspace-root <path>", "required previous owner when managed legacy state exists").option("--dry-run", "show the retirement plan without writing (default)", false).option("--apply", "apply the exact reviewed retirement plan", false).option("--json", "print the install plan as JSON", false).action(async (packageName, options) => {
+  if (options.apply && options.dryRun) throw new Error("--apply cannot be combined with --dry-run.");
+  await runExactMcpRetirement(packageName, { ...options, dryRun: !options.apply });
+});
 program.command("eject").description("copy a managed artifact into local ownership").argument("<item>", "package/type/name").option("-t, --target-root <path>", "workspace root", process.cwd()).action(async (item, options) => {
   const targetRoot = normalizeTargetRoot(options.targetRoot);
   const result = await ejectArtifact(targetRoot, item);
@@ -12697,7 +13345,7 @@ journalCommand.command("list").description("show pending apply journals for reso
     if (!journal) continue;
     pending += 1;
     console.log(`PENDING ${state.adapter.name}/${state.installationType} at ${state.installRoot}`);
-    console.log(`  journal: ${join48(state.installRoot, ".agentwheel", `${state.state.stateKey}.apply-journal.json`)}`);
+    console.log(`  journal: ${join49(state.installRoot, ".agentwheel", `${state.state.stateKey}.apply-journal.json`)}`);
     console.log(`  stateKey: ${state.state.stateKey}`);
     console.log(`  createdAt: ${journal.createdAt}`);
     console.log(`  updatedAt: ${journal.updatedAt}`);
@@ -12818,7 +13466,11 @@ async function runInstallCommand(nameOrSource, options, behavior) {
     let extraPackage;
     if (nameOrSource && !configured) {
       try {
-        let entry = await packageEntryFromSource(nameOrSource, target.workspaceRoot, { ...targetOptions, adapter: targetOptions.adapter ?? target.adapter });
+        let entry = await packageEntryFromSource(nameOrSource, target.workspaceRoot, {
+          ...targetOptions,
+          adapter: targetOptions.adapter ?? target.adapter,
+          deferGraphRendering: true
+        });
         if (targetOptions.multiAdapterSource) {
           entry = packageEntryWithAdapterSuffix(entry);
         }
@@ -12849,7 +13501,7 @@ async function runInstallCommand(nameOrSource, options, behavior) {
           if (reloaded) console.log(`Reloaded runtime via ${formatReloadCommands(target.reloadCommands)}.`);
         }
       }
-      await rm12(result.bundle.root, { recursive: true, force: true });
+      await rm13(result.bundle.root, { recursive: true, force: true });
       if (result.plan.hasBlockingChanges) process.exitCode = 1;
     }
     if (behavior.apply && extraPackage && !targetOptions.onlySource) {
@@ -12915,6 +13567,7 @@ async function buildPlanReport(nameOrSource, options) {
         let entry = await packageEntryFromSource(nameOrSource, target.workspaceRoot, {
           ...targetOptions,
           adapter: targetOptions.adapter ?? target.adapter,
+          deferGraphRendering: true,
           warn: collectWarning
         });
         if (targetOptions.multiAdapterSource) {
@@ -12944,7 +13597,7 @@ async function buildPlanReport(nameOrSource, options) {
     for (const result of results) {
       reportTargets.push(installPlanReportTarget(result.plan, result.graphLockDigest));
       reportWarnings.push(...result.warnings);
-      await rm12(result.bundle.root, { recursive: true, force: true });
+      await rm13(result.bundle.root, { recursive: true, force: true });
     }
   }
   return planReport(reportTargets, reportWarnings);
@@ -12997,16 +13650,26 @@ async function packageEntryFromSource(source, targetRoot, options) {
       `No available version of ${provisionalName} satisfies ${options.version}; latest overall is ${initialVersion.availability.latestOverall ?? "unknown"}.`
     );
   }
-  const bundle = await stageSource(driver, resolvedSource, {
+  const bundle = options.deferGraphRendering ? await stageSourceRaw(driver, resolvedSource, {
+    cacheRoot: join49(targetRoot, ".agentwheel", "cache"),
+    mode: options.mode,
+    ref: initialVersion?.ref,
+    frozenLock: lockMode
+  }) : await stageSource(driver, resolvedSource, {
     workspaceRoot: targetRoot,
     adapter,
-    cacheRoot: join48(targetRoot, ".agentwheel", "cache"),
+    cacheRoot: join49(targetRoot, ".agentwheel", "cache"),
     mode: options.mode,
     ref: initialVersion?.ref,
     frozenLock: lockMode,
     select: selectedArtifacts
   });
-  const installationType = resolveInstallationTypeForArtifacts(adapter, bundle.artifacts.map((artifact) => artifact.type), options.installationType);
+  const installationArtifacts = options.deferGraphRendering ? filterArtifactsBySelection(bundle.artifacts, selectedArtifacts).filter((artifact) => !artifact.runtimes?.length || artifact.runtimes.includes(adapter.name)) : bundle.artifacts;
+  const installationType = resolveInstallationTypeForArtifacts(
+    adapter,
+    installationArtifacts.map((artifact) => artifact.type),
+    options.installationType
+  );
   try {
     return {
       name: options.name ?? resolvedInput.registryEntry?.name ?? bundle.source.packageName ?? source,
@@ -13026,7 +13689,7 @@ async function packageEntryFromSource(source, targetRoot, options) {
       overrides: overrideArtifactsFromOptions(options)
     };
   } finally {
-    await rm12(bundle.root, { recursive: true, force: true });
+    await rm13(bundle.root, { recursive: true, force: true });
   }
 }
 function findConfiguredPackage(packages, value) {
@@ -13036,6 +13699,64 @@ function findConfiguredPackageForTarget(packages, value, options, target) {
   const matches = packages.filter((pkg) => pkg.name === value || pkg.source === value);
   return options.multiAdapterSource ? matches.find((pkg) => pkg.adapter === target.adapter) : matches[0];
 }
+async function configuredPackageForSkill(target, packages, skillName, options, explicitPackageName) {
+  const selector = `skills/${skillName}`;
+  if (explicitPackageName) {
+    const pkg = findConfiguredPackage(packages, explicitPackageName);
+    if (!pkg) throw new Error(`Configured package not found: ${explicitPackageName}`);
+    if (!await packageSelectsSkillForTarget(target, pkg, selector, options)) {
+      throw new Error(`Configured package '${pkg.name}' does not select ${selector}.`);
+    }
+    return pkg;
+  }
+  const adapterPackages = packages.filter((pkg) => pkg.adapter === target.adapter);
+  const candidates = adapterPackages.length > 0 ? adapterPackages : packages;
+  const matches = [];
+  for (const pkg of candidates) {
+    if (await packageSelectsSkillForTarget(target, pkg, selector, options)) matches.push(pkg);
+  }
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    throw new Error(
+      `Skill '${skillName}' has multiple configured owners: ${matches.map((pkg) => pkg.name).sort().join(", ")}. Pass --package <name>.`
+    );
+  }
+  throw new Error(
+    `No configured owner found for skill '${skillName}'. Add ${selector} to one package selection or pass --package <name>.`
+  );
+}
+async function packageSelectsSkillForTarget(target, pkg, selector, options) {
+  const explicitSelection = normalizeArtifactSelectors(pkg.select, pkg.skills);
+  if (explicitSelection && !explicitSelection.some((candidate) => candidate === selector)) return false;
+  const groups = /* @__PURE__ */ new Map();
+  const group = graphGroupForPackage(groups, target, pkg, options);
+  const adapter = await resolveAdapterForTarget(group.target, group.adapterOptions);
+  const graphLockPath = graphLockPathForTarget(
+    group.target.workspaceRoot,
+    targetKeyForTarget(group.target, adapter.name),
+    adapter.name,
+    targetFingerprintParts(group.target, adapter, group.adapterOptions, group.installationType)
+  );
+  if (await pathExists(graphLockPath)) {
+    const lock = await readGraphLock(graphLockPath);
+    const root = lock.canonical.roots.find((candidate) => candidate.rootId === pkg.name);
+    if (root?.selected.includes(selector)) return true;
+  }
+  const results = await buildGraphPlansForTarget(target, void 0, {
+    ...options,
+    scope: pkg.name,
+    onlySource: true,
+    dryRun: true,
+    suppressEmptyMessage: true
+  }, { mode: "install" });
+  try {
+    return results.some((result) => result.bundle.graphLock.canonical.roots.some(
+      (root) => root.rootId === pkg.name && root.selected.includes(selector)
+    ));
+  } finally {
+    await Promise.all(results.map((result) => rm13(result.bundle.root, { recursive: true, force: true })));
+  }
+}
 function noDepsFromOptions(options) {
   return options.noDeps === true || options.deps === false;
 }
@@ -13156,6 +13877,69 @@ function adapterOptionsForTarget(target, options) {
 function targetKeyForTarget(target, adapterName) {
   return target.targetKey ?? target.agentName ?? adapterName ?? target.source;
 }
+async function runExactMcpRetirement(packageName, options) {
+  const normalizedOptions = normalizeRuntimeScopeOptions(options);
+  const targets = await resolveCliTargets(normalizedOptions);
+  if (targets.length !== 1) {
+    throw new Error(`Exact MCP retirement requires exactly one runtime target, found ${targets.length}.`);
+  }
+  const target = targets[0];
+  const expectedFromWorkspaceOwner = options.fromWorkspaceRoot ? workspaceOwnerForRoot(normalizeCliPath(options.fromWorkspaceRoot)) : void 0;
+  const results = await buildGraphPlansForTarget(target, void 0, {
+    ...normalizedOptions,
+    scope: packageName,
+    onlySource: true,
+    retireExactMcp: true,
+    expectedFromWorkspaceOwner,
+    dryRun: true
+  }, { mode: "install" });
+  if (results.length !== 1) {
+    await Promise.all(results.map((result2) => rm13(result2.bundle.root, { recursive: true, force: true })));
+    throw new Error(`Exact MCP retirement requires one package plan, found ${results.length}.`);
+  }
+  const result = results[0];
+  try {
+    console.log(options.json ? JSON.stringify(result.plan, null, 2) : formatGraphPlan(result));
+    if (result.plan.hasBlockingChanges) {
+      process.exitCode = 1;
+      return;
+    }
+    if (!options.dryRun) {
+      await uninstall(result.plan, { transport: transportForTarget(target) });
+      console.log(`Retired exact MCP contribution for ${result.plan.adapter} at ${result.plan.targetRoot}.`);
+    }
+  } finally {
+    await rm13(result.bundle.root, { recursive: true, force: true });
+  }
+}
+async function runSkillUpdateCommand(skillName, options) {
+  const normalizedOptions = normalizeRuntimeScopeOptions(options);
+  const composite = await resolveSelectedCompositeProfile(normalizedOptions);
+  if (composite) {
+    await runCompositeSkillUpdate(
+      composite.workspaceRoot,
+      composite.name,
+      composite.profile,
+      skillName,
+      options.package,
+      normalizedOptions
+    );
+    return;
+  }
+  const targets = await resolveCliTargets(normalizedOptions, { preferAllProfile: true });
+  for (const target of targets) {
+    const config = await readMergedWorkspaceConfig(target.workspaceRoot);
+    const owner = await configuredPackageForSkill(target, config.packages, skillName, normalizedOptions, options.package);
+    const mode = owner.mode === "tracking" ? "update" : "install";
+    console.log(`Skill ${skillName}: ${owner.name} (${mode}).`);
+    await runConfiguredGraphPackages(target, {
+      ...normalizedOptions,
+      scope: owner.name,
+      onlySource: true,
+      replaceConflict: options.adopt === true
+    }, { mode });
+  }
+}
 async function runConfiguredGraphPackages(target, options, behavior) {
   const results = await buildGraphPlansForTarget(target, void 0, options, behavior);
   for (const result of results) {
@@ -13177,7 +13961,7 @@ async function runConfiguredGraphPackages(target, options, behavior) {
       console.log(`Applied ${result.plan.adapter} at ${result.plan.targetRoot}.`);
       if (reloaded) console.log(`Reloaded runtime via ${formatReloadCommands(target.reloadCommands)}.`);
     }
-    await rm12(result.bundle.root, { recursive: true, force: true });
+    await rm13(result.bundle.root, { recursive: true, force: true });
     if (result.plan.hasBlockingChanges) process.exitCode = 1;
   }
 }
@@ -13191,14 +13975,20 @@ async function buildGraphPlansForTarget(target, source, options, behavior) {
   const scopedPackage = targetOptions.scope ? findConfiguredPackage(config.packages, targetOptions.scope) : void 0;
   const scopedRootId = scopedPackage?.name ?? (source ? targetOptions.scope : void 0);
   if (targetOptions.scope && !scopedPackage && !source) throw new Error(`Configured package not found: ${targetOptions.scope}`);
-  if (!source || !targetOptions.onlySource) {
+  if (scopedPackage && targetOptions.onlySource) {
+    const group = graphGroupForPackage(groups, target, scopedPackage, targetOptions);
+    group.packages.push(scopedPackage);
+  } else if (!source || !targetOptions.onlySource) {
     for (const pkg of config.packages) {
       const group = graphGroupForPackage(groups, target, pkg, targetOptions);
       group.packages.push(pkg);
     }
   }
   if (source) {
-    let entry = targetOptions.extraPackage ?? await packageEntryFromSource(source, target.workspaceRoot, targetOptions);
+    let entry = targetOptions.extraPackage ?? await packageEntryFromSource(source, target.workspaceRoot, {
+      ...targetOptions,
+      deferGraphRendering: true
+    });
     if (targetOptions.multiAdapterSource) {
       entry = packageEntryWithAdapterSuffix(entry);
     }
@@ -13329,6 +14119,7 @@ async function buildGraphPlansForTarget(target, source, options, behavior) {
       targetKey: targetKeyForTarget(group.target, adapter.name),
       targetFingerprintParts: targetFingerprintParts(group.target, adapter, group.adapterOptions, group.installationType),
       installationType: group.installationType,
+      stateKey: group.target.stateKey,
       noDeps: noDepsFromOptions(targetOptions),
       includeSuggestions: targetOptions.withSuggestions,
       suggestionAliases: suggestionAliasesFromOptions(targetOptions),
@@ -13342,12 +14133,14 @@ async function buildGraphPlansForTarget(target, source, options, behavior) {
       isTTY: process.stdin.isTTY === true,
       forceDrift: targetOptions.forceDrift,
       forceConflict: targetOptions.forceConflict,
-      replaceConflict: targetOptions.replaceConflict
+      replaceConflict: targetOptions.replaceConflict,
+      retireExactMcp: targetOptions.retireExactMcp,
+      expectedFromWorkspaceOwner: targetOptions.expectedFromWorkspaceOwner
     });
     if ((behavior.mode === "install" || behavior.mode === "update") && scopedRootId) {
       const state = installStateForTarget(group.target, adapter, group.adapterOptions, group.installationType);
       const manifest = await readInstallManifest(state.installRoot, adapter.name, transport, state);
-      results.push(behavior.mode === "update" && previousGroupLock ? scopeUpdatePlanToRoot(result, scopedRootId, previousGroupLock, manifest) : scopeInstallPlanToRoot(result, scopedRootId, manifest));
+      results.push(previousGroupLock ? scopeUpdatePlanToRoot(result, scopedRootId, previousGroupLock, manifest) : scopeInstallPlanToRoot(result, scopedRootId, manifest));
     } else if (scopedDependencyUpdate) {
       const state = installStateForTarget(group.target, adapter, group.adapterOptions, group.installationType);
       const manifest = await readInstallManifest(state.installRoot, adapter.name, transport, state);
@@ -13394,7 +14187,7 @@ function scopeUpdatePlanToDependencies(result, selectors, previousLock, manifest
     selectedPreviousNodeIds,
     selectedRootIds
   );
-  const graphLockDigest = createHash14("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+  const graphLockDigest = createHash15("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
   return {
     ...result,
     bundle: { ...result.bundle, graphLock },
@@ -13562,7 +14355,7 @@ function scopeUpdatePlanToRoot(result, rootId, previousLock, manifest) {
     selectedPreviousNodeIds,
     /* @__PURE__ */ new Set([rootId])
   );
-  const graphLockDigest = createHash14("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+  const graphLockDigest = createHash15("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
   return {
     ...scoped,
     bundle: { ...scoped.bundle, graphLock },
@@ -13634,7 +14427,7 @@ function keepManifestEntryOperation(entry, targetRoot, scopeDescription, operati
     artifactType: entry.artifactType,
     artifactName: entry.artifactName,
     kind: entry.kind,
-    destPath: operation?.destPath ?? join48(targetRoot, entry.path),
+    destPath: operation?.destPath ?? join49(targetRoot, entry.path),
     relativeDestPath: entry.path,
     desiredHash: entry.sourceHash,
     currentHash: operation?.currentHash ?? entry.hash,
@@ -13751,7 +14544,7 @@ async function uninstallConfiguredPackage(target, packageName, options) {
     if (!options.dryRun) {
       console.log(formatUninstallResult(result));
     }
-    if (renderedRoot) await rm12(renderedRoot, { recursive: true, force: true });
+    if (renderedRoot) await rm13(renderedRoot, { recursive: true, force: true });
     if (plan.hasBlockingChanges) process.exitCode = 1;
   }
 }
@@ -13802,14 +14595,15 @@ function targetFingerprintParts(target, adapter, options, installationType) {
     agentName: target.agentName,
     targetRoot: target.targetRoot,
     transport: target.transport,
-    ssh: target.ssh
+    ssh: target.ssh,
+    stateKey: target.stateKey
   };
 }
 function installStateForTarget(target, adapter, options, installationType) {
   const targetFingerprint = targetFingerprintDigest(target, adapter, options, installationType);
   return {
     installationType,
-    stateKey: stateKeyFor(adapter.name, { installationType, targetFingerprint }),
+    stateKey: target.stateKey ?? stateKeyFor(adapter.name, { installationType, targetFingerprint }),
     installRoot: installRootForAdapterInstallationType(adapter, target.targetRoot, installationType, target.transport === "ssh")
   };
 }
@@ -14005,6 +14799,44 @@ async function runCompositeUpdate(workspaceRoot, profileName, profile, packageNa
     if (result.stderr.trim()) console.error(result.stderr.trimEnd());
   }
 }
+async function runCompositeSkillUpdate(workspaceRoot, profileName, profile, skillName, packageName, options) {
+  const preflight = await collectCompositeStatus(workspaceRoot, profileName, profile, options);
+  printStatusReport(preflight);
+  const blockers = preflight.members.filter((member) => blocksCompositeApply(member.health));
+  if (blockers.length > 0) {
+    throw new Error(
+      "Composite skill update blocked before member execution: " + blockers.map((member) => `${member.id}=${member.health}`).join(", ")
+    );
+  }
+  const incomingChain = parseCompositeChain();
+  const memberChain = [...incomingChain, compositeKey(workspaceRoot, profileName)];
+  for (const member of profile.members) {
+    if (!options.dryRun) {
+      const before = preflight.members.find((candidate) => candidate.id === member.id);
+      const revalidated = await collectCompositeMembers({
+        cliVersion: CLI_VERSION,
+        workspaceRoot,
+        profileName,
+        profileTtlSeconds: profile.refreshTtlSeconds,
+        members: [member],
+        refresh: true,
+        chain: incomingChain
+      });
+      const current = revalidated[0];
+      if (blocksCompositeApply(current.health)) {
+        throw new Error(`Composite skill update stopped before ${member.id}: revalidation is ${current.health}.`);
+      }
+      if (statusRevisionSignature(before?.report) !== statusRevisionSignature(current.report)) {
+        throw new Error(`Composite skill update stopped before ${member.id}: member revision changed after preflight.`);
+      }
+    }
+    const args = compositeSkillUpdateArguments(member.profile, skillName, packageName, options);
+    console.log(`${options.dryRun ? "Plan" : "Update"} member ${member.id}:`);
+    const result = await runMemberAgentwheel(member, workspaceRoot, args, memberChain);
+    if (result.stdout.trim()) console.log(result.stdout.trimEnd());
+    if (result.stderr.trim()) console.error(result.stderr.trimEnd());
+  }
+}
 async function runCompositeInstall(workspaceRoot, profileName, profile, nameOrSource, options, behavior) {
   const preflight = await collectCompositeStatus(workspaceRoot, profileName, profile, options);
   printStatusReport(preflight);
@@ -14080,6 +14912,21 @@ function compositeUpdateArguments(profile, packageName, options) {
   if (options.yes) args.push("--yes");
   return args;
 }
+function compositeSkillUpdateArguments(profile, skillName, packageName, options) {
+  const args = ["skill", "update", skillName, "--profile", profile];
+  if (packageName) args.push("--package", packageName);
+  if (options.dryRun) args.push("--dry-run");
+  if (options.adopt) args.push("--adopt");
+  if (options.refresh) args.push("--refresh");
+  if (options.forceDrift) args.push("--force-drift");
+  if (options.allowAdapterCode) args.push("--allow-adapter-code");
+  if (options.noDeps) args.push("--no-deps");
+  if (options.frozenLock) args.push("--frozen-lock");
+  if (options.offline) args.push("--offline");
+  for (const trust of options.trust ?? []) args.push("--trust", trust);
+  if (options.yes) args.push("--yes");
+  return args;
+}
 function statusRevisionSignature(report) {
   if (!report) return "missing";
   return JSON.stringify({
@@ -14202,7 +15049,7 @@ async function collectPendingInstallWork(target, options) {
     const message = error instanceof Error ? error.message : String(error);
     return { pendingCount: 0, driftCount: 0, conflictCount: 0, counts: {}, error: message };
   } finally {
-    await Promise.all(results.map((result) => rm12(result.bundle.root, { recursive: true, force: true })));
+    await Promise.all(results.map((result) => rm13(result.bundle.root, { recursive: true, force: true })));
   }
 }
 async function printDoctor(target, options) {
@@ -14219,12 +15066,12 @@ async function printDoctor(target, options) {
   const requestedSkills = doctorSkillRequests(target, options);
   const skills = [];
   for (const request of requestedSkills) {
-    const skillPath = join48(state.installRoot, targetMapping.dest, request.name);
+    const skillPath = join49(state.installRoot, targetMapping.dest, request.name);
     const exists = await pathExists(skillPath);
     const manifestEntry = manifest?.entries.find((entry) => {
       if (entry.artifactType !== "skills") return false;
       const legacyInstallName = "installName" in entry && typeof entry.installName === "string" ? entry.installName : void 0;
-      return entry.artifactName === request.name || legacyInstallName === request.name || entry.path === join48(targetMapping.dest, request.name);
+      return entry.artifactName === request.name || legacyInstallName === request.name || entry.path === join49(targetMapping.dest, request.name);
     });
     const status = manifestEntry ? "managed" : exists ? "present-unmanaged" : "missing";
     skills.push({
@@ -14304,7 +15151,7 @@ function doctorSkillLabel(name) {
   return `${name} skill`;
 }
 function isSyncwheelWorkspace(targetRoot) {
-  return existsSync(join48(targetRoot, ".syncwheel", "manifest.json"));
+  return existsSync(join49(targetRoot, ".syncwheel", "manifest.json"));
 }
 function skillInstallCommand(adapter, installationType, options, skill, behavior = {}) {
   const args = [
@@ -14336,6 +15183,11 @@ function shellQuoteArg2(value) {
 function collectSelectOption(value, previous) {
   return [...previous, ...splitSelectorList(value)];
 }
+function parsePositiveInteger(value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) throw new Error(`Expected a positive integer, got: ${value}`);
+  return parsed;
+}
 function collectSkillOption(value, previous) {
   return [...previous, ...splitSelectorList(value)];
 }
@@ -14452,10 +15304,10 @@ function filterUninstallPlanBySelection(plan, selected) {
   };
 }
 async function initPackage(root) {
-  await mkdir23(join48(root, "instructions"), { recursive: true });
-  await mkdir23(join48(root, "rules"), { recursive: true });
-  await mkdir23(join48(root, "skills"), { recursive: true });
-  const manifestPath = join48(root, "openpack.json");
+  await mkdir24(join49(root, "instructions"), { recursive: true });
+  await mkdir24(join49(root, "rules"), { recursive: true });
+  await mkdir24(join49(root, "skills"), { recursive: true });
+  const manifestPath = join49(root, "openpack.json");
   const manifest = {
     schemaVersion: 2,
     name: "example/agentwheel-package",
@@ -14468,10 +15320,10 @@ async function initPackage(root) {
   };
   await writeFile22(manifestPath, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-  await writeFile22(join48(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
+  await writeFile22(join49(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
 }
 async function defaultBootstrapPackage(_root) {
-  const packageRoot = await findAgentwheelPackageRoot(dirname32(fileURLToPath3(import.meta.url)));
+  const packageRoot = await findAgentwheelPackageRoot(dirname33(fileURLToPath3(import.meta.url)));
   if (!packageRoot) return void 0;
   return {
     name: "agentwheel",
@@ -14518,7 +15370,7 @@ async function findAgentwheelPackageRoot(start) {
   let current = resolve22(start);
   while (true) {
     if (await findPackageManifestPath(current, { warnLegacy: false })) return current;
-    const parent = dirname32(current);
+    const parent = dirname33(current);
     if (parent === current) return void 0;
     current = parent;
   }