agentwheel 0.10.0 → 0.11.0

package/README.md

@@ -34,9 +34,9 @@ agentwheel install
 No lock-in. No central gatekeeper. Packages live in plain git repos or local folders, customizations
 live in your workspace, and runtimes stay generated output.
 
-> **Status: early (v0.9).** v0.9 switches the public CLI vocabulary to package-manager verbs:
-> `add`, `install`, `update`, and `uninstall`. A hidden `sync` shim remains for one release only
-> so old bootstrapped skills can self-update; use `install` in all new docs and scripts.
+> **Status: early (v0.11).** The public CLI vocabulary is package-manager style:
+> `add`, `install`, `update`, and `uninstall`. A hidden `sync` shim remains for old bootstrapped
+> skills; use `install` in all new docs and scripts.
 
 ## Supported runtimes & resources
 
@@ -272,6 +272,58 @@ still owned by another configured package.
 }
 ```
 
+### Source Overrides
+
+Use package-level `overrides` when a workspace intentionally wants one selected source to replace
+an artifact that arrives from another package, such as a forked skill replacing the same skill
+pulled in by a meta-package. Overrides are explicit; package array order never decides precedence.
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "packages": [
+    {
+      "name": "nestdev-must-have-core",
+      "source": "github:NestDevLab/agent-must-have#core",
+      "driver": "git",
+      "adapter": "codex",
+      "mode": "tracking"
+    },
+    {
+      "name": "agent-toolkit-nestdev",
+      "source": "github:Yehonal/agent-toolkit#main",
+      "driver": "git",
+      "adapter": "codex",
+      "mode": "tracking",
+      "select": [
+        "rules/self-improve-on-correction.md",
+        "skills/self-improve"
+      ],
+      "overrides": [
+        "github:FrancescoBorzi/agent-toolkit::rules/self-improve-on-correction.md",
+        "github:FrancescoBorzi/agent-toolkit::skills/self-improve"
+      ]
+    }
+  ]
+}
+```
+
+The `source::type/name` selector identifies the artifact to replace. `github:owner/repo` matches
+that repository at any ref; add `#main` or another ref to narrow it. The replacing package must
+select exactly one artifact with the same `type/name`, and the override must match exactly one
+losing artifact. Otherwise planning fails instead of hiding a collision.
+
+The same declaration can be created from the CLI:
+
+```bash
+agentwheel add github:Yehonal/agent-toolkit#main \
+  --skill self-improve \
+  --override 'github:FrancescoBorzi/agent-toolkit::skills/self-improve'
+```
+
+`agentwheel plan`, `agentwheel deps tree`, and `agentwheel deps why` print `OVERRIDE` lines for
+these decisions, and graph locks store them for review.
+
 Migrating an existing legacy package takes one command:
 
 ```bash
@@ -285,7 +337,9 @@ Drift detection blocks accidental edits to generated runtime files. Intentional
 
 - **Layer** local instructions with `agentwheel remember`.
 - **Add** separate local artifacts under `.agentwheel/additions`.
-- **Override** an upstream item under `.agentwheel/overrides`.
+- **Override content** for an upstream item under `.agentwheel/overrides`.
+- **Override source precedence** with package `overrides` when a forked source should replace a
+  colliding artifact from another package.
 - **Eject** an item into `.agentwheel/ejected` when you want local ownership.
 
 ## Custom And Private Runtimes

package/dist/index.js

@@ -297,7 +297,8 @@ var graphLockRootSchema = z3.object({
   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()
+  aliases: z3.record(z3.string(), z3.string().min(1)).optional(),
+  overrides: z3.array(z3.string().min(1)).optional()
 });
 var graphLockEdgeSchema = z3.object({
   from: z3.string().min(1),
@@ -346,6 +347,15 @@ var graphLockNamespacingSchema = z3.object({
   installName: z3.string().min(1),
   reason: z3.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),
+  type: artifactTypeSchema,
+  name: z3.string().min(1),
+  installName: z3.string().min(1)
+});
 var graphLockCanonicalSchema = z3.object({
   targetFingerprint: z3.string().min(1).optional(),
   roots: z3.array(graphLockRootSchema),
@@ -354,6 +364,7 @@ var graphLockCanonicalSchema = z3.object({
   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 graphLockSchema = z3.object({
@@ -384,7 +395,11 @@ function canonicalizeGraphLock(lock) {
     version: 1,
     canonical: {
       targetFingerprint: parsed.canonical.targetFingerprint,
-      roots: [...parsed.canonical.roots].map((root) => ({ ...root, selected: sortedUnique(root.selected) })).sort((a, b) => `${a.rootId}:${a.graphNodeId}`.localeCompare(`${b.rootId}:${b.graphNodeId}`)),
+      roots: [...parsed.canonical.roots].map((root) => ({
+        ...root,
+        selected: sortedUnique(root.selected),
+        overrides: root.overrides ? sortedUnique(root.overrides) : void 0
+      })).sort((a, b) => `${a.rootId}:${a.graphNodeId}`.localeCompare(`${b.rootId}:${b.graphNodeId}`)),
       nodes: [...parsed.canonical.nodes].map((node) => ({
         ...node,
         requiredBy: sortedUnique(node.requiredBy),
@@ -395,6 +410,7 @@ function canonicalizeGraphLock(lock) {
       includeEdges: [...parsed.canonical.includeEdges].sort((a, b) => `${a.fromNodeId}:${a.alias}:${a.toNodeId}:${a.selector}`.localeCompare(`${b.fromNodeId}:${b.alias}:${b.toNodeId}:${b.selector}`)),
       artifacts: [...parsed.canonical.artifacts].map((artifact) => ({ ...artifact, owners: sortedUnique(artifact.owners) })).sort((a, b) => a.logicalSelector.localeCompare(b.logicalSelector)),
       namespacing: [...parsed.canonical.namespacing].sort((a, b) => `${a.type}:${a.installName}:${a.graphNodeId}:${a.name}`.localeCompare(`${b.type}:${b.installName}:${b.graphNodeId}:${b.name}`)),
+      overrides: [...parsed.canonical.overrides].sort((a, b) => `${a.type}:${a.installName}:${a.graphNodeId}:${a.overriddenGraphNodeId}`.localeCompare(`${b.type}:${b.installName}:${b.graphNodeId}:${b.overriddenGraphNodeId}`)),
       plainNameIncumbents: [...parsed.canonical.plainNameIncumbents].sort((a, b) => `${a.adapter}:${a.targetFingerprint}:${a.type}:${a.name}`.localeCompare(`${b.adapter}:${b.targetFingerprint}:${b.type}:${b.name}`))
     }
   };
@@ -2138,6 +2154,9 @@ function formatGraphPlan(result) {
   for (const decision of result.bundle.graphLock.canonical.namespacing) {
     lines.push(`NAMESPACE ${decision.graphNodeId}:${decision.type}/${decision.name} -> ${decision.type}/${decision.installName} (${decision.reason})`);
   }
+  for (const decision of result.bundle.graphLock.canonical.overrides) {
+    lines.push(`OVERRIDE ${decision.graphNodeId}:${decision.type}/${decision.name} replaces ${decision.overriddenGraphNodeId}:${decision.type}/${decision.name} via ${decision.rootId} (${decision.selector})`);
+  }
   if (result.graphDiff.length > 0) {
     lines.push("Graph diff:");
     lines.push(...result.graphDiff);
@@ -2175,6 +2194,9 @@ function formatLockDependencyTree(lock) {
   for (const decision of lock.canonical.namespacing) {
     lines.push(`NAMESPACE ${decision.graphNodeId}:${decision.type}/${decision.name} -> ${decision.type}/${decision.installName} (${decision.reason})`);
   }
+  for (const decision of lock.canonical.overrides) {
+    lines.push(`OVERRIDE ${decision.graphNodeId}:${decision.type}/${decision.name} replaces ${decision.overriddenGraphNodeId}:${decision.type}/${decision.name} via ${decision.rootId} (${decision.selector})`);
+  }
   return lines.join("\n");
 }
 function formatDepsWhy(lock, manifest, query) {
@@ -2197,6 +2219,9 @@ function formatDepsWhy(lock, manifest, query) {
   }
   const namespace = lock.canonical.namespacing.find((decision) => decision.graphNodeId === match.graphNodeId && decision.type === match.type && decision.name === match.name);
   lines.push(namespace ? `NAME    ${namespace.reason}: ${namespace.type}/${namespace.name} -> ${namespace.type}/${namespace.installName}` : `NAME    plain: ${match.type}/${match.name}`);
+  for (const override of lock.canonical.overrides.filter((decision) => decision.graphNodeId === match.graphNodeId && decision.type === match.type && decision.name === match.name)) {
+    lines.push(`OVERRIDE replaces ${override.overriddenGraphNodeId}:${override.type}/${override.name} via ${override.rootId}`);
+  }
   return lines.join("\n");
 }
 function formatSelected(selected, reasons) {
@@ -3776,7 +3801,8 @@ var workspacePackageSchema = z6.object({
   requestedRef: z6.string().min(1).optional(),
   select: z6.array(z6.string().min(1)).optional(),
   skills: z6.array(z6.string().min(1)).optional(),
-  aliases: z6.record(z6.string(), z6.string().min(1)).optional()
+  aliases: z6.record(z6.string(), z6.string().min(1)).optional(),
+  overrides: z6.array(z6.string().min(1)).optional()
 });
 var workspaceProfileRuntimeSchema = z6.object({
   agent: z6.string().min(1).optional(),
@@ -4315,6 +4341,7 @@ async function resolveDependencyGraph(roots, options) {
       requiredBy: `workspace:${rootId}`,
       rootId,
       aliases: root.aliases,
+      overrides: root.overrides,
       useLock: root.useLock ?? options.lockedResolution,
       depth: 0,
       optional: false,
@@ -4346,7 +4373,7 @@ async function resolveDependencyGraph(roots, options) {
     generatedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
   };
 }
-function createGraphLock(graph, artifacts = [], targetFingerprint, includeEdges = [], namespacing = []) {
+function createGraphLock(graph, artifacts = [], targetFingerprint, includeEdges = [], namespacing = [], overrides = []) {
   const roots = graph.roots.map((root) => ({
     rootId: root.rootId,
     source: root.source,
@@ -4354,7 +4381,8 @@ function createGraphLock(graph, artifacts = [], targetFingerprint, includeEdges
     graphNodeId: root.graphNodeId,
     mode: root.mode,
     selected: root.selected,
-    aliases: root.aliases
+    aliases: root.aliases,
+    overrides: root.overrides
   }));
   return {
     version: 1,
@@ -4366,6 +4394,7 @@ function createGraphLock(graph, artifacts = [], targetFingerprint, includeEdges
       includeEdges,
       artifacts,
       namespacing,
+      overrides,
       plainNameIncumbents: []
     }
   };
@@ -4462,7 +4491,8 @@ Run without ${lockLabel === "Offline" ? "--offline" : "--frozen-lock"} first.`
         graphNodeId: state.node.id,
         mode: state.node.mode,
         selected: state.node.selected,
-        aliases: requirement.aliases
+        aliases: requirement.aliases,
+        overrides: requirement.overrides
       });
     }
     if (requirement.parentId && requirement.alias) {
@@ -5069,7 +5099,8 @@ function diffGraphLocks(previous, next) {
   return [
     ...diffNodes(previous.canonical.nodes, next.canonical.nodes),
     ...diffIncludeEdges(previous.canonical.includeEdges, next.canonical.includeEdges),
-    ...diffNamespacing(previous.canonical.namespacing, next.canonical.namespacing)
+    ...diffNamespacing(previous.canonical.namespacing, next.canonical.namespacing),
+    ...diffOverrides(previous.canonical.overrides, next.canonical.overrides)
   ];
 }
 function diffNodes(previous, next) {
@@ -5131,6 +5162,23 @@ function diffNamespacing(previous, next) {
   }
   return lines.sort((a, b) => a.localeCompare(b));
 }
+function diffOverrides(previous, next) {
+  const previousByKey = new Map(previous.map((decision) => [overrideKey(decision), decision]));
+  const nextByKey = new Map(next.map((decision) => [overrideKey(decision), decision]));
+  const lines = [];
+  for (const [key, decision] of nextByKey) {
+    const old = previousByKey.get(key);
+    if (!old) {
+      lines.push(`ADDED override ${formatOverride(decision)}`);
+    } else if (old.graphNodeId !== decision.graphNodeId || old.installName !== decision.installName) {
+      lines.push(`CHANGED override ${decision.selector} ${old.graphNodeId}:${old.type}/${old.name} -> ${decision.graphNodeId}:${decision.type}/${decision.name}`);
+    }
+  }
+  for (const [key, decision] of previousByKey) {
+    if (!nextByKey.has(key)) lines.push(`REMOVED override ${formatOverride(decision)}`);
+  }
+  return lines.sort((a, b) => a.localeCompare(b));
+}
 function stableNodeKey(node) {
   return `${node.normalizedSource}\0${node.name}`;
 }
@@ -5150,9 +5198,15 @@ function formatIncludeEdge(edge) {
 function namespaceKey(decision) {
   return `${decision.graphNodeId}\0${decision.type}\0${decision.name}`;
 }
+function overrideKey(decision) {
+  return `${decision.rootId}\0${decision.selector}\0${decision.overriddenGraphNodeId}\0${decision.type}\0${decision.name}`;
+}
 function formatNamespace(decision) {
   return `${decision.graphNodeId}:${decision.type}/${decision.name} -> ${decision.type}/${decision.installName} (${decision.reason})`;
 }
+function formatOverride(decision) {
+  return `${decision.graphNodeId}:${decision.type}/${decision.name} replaces ${decision.overriddenGraphNodeId}:${decision.type}/${decision.name} via ${decision.rootId} (${decision.selector})`;
+}
 function short(hash) {
   return hash.slice(0, 12);
 }
@@ -5254,13 +5308,13 @@ async function renderGraphForTarget(graph, targetContext = {}) {
       owners: [...rawNode.node.requiredBy].sort((a, b) => a.localeCompare(b))
     })));
   }
-  const { artifacts: namedArtifacts, namespacing } = assignInstallNames(graph, artifacts);
+  const { artifacts: namedArtifacts, namespacing, overrides } = assignInstallNames(graph, artifacts);
   const sortedArtifacts = namedArtifacts.sort((a, b) => a.logicalSelector.localeCompare(b.logicalSelector));
   return {
     root,
     nodes: graph.nodes,
     artifacts: sortedArtifacts,
-    graphLock: createGraphLock(graph, sortedArtifacts.map(lockArtifactFor), targetContext.targetFingerprint, [...includeEdges.values()], namespacing)
+    graphLock: createGraphLock(graph, sortedArtifacts.map(lockArtifactFor), targetContext.targetFingerprint, [...includeEdges.values()], namespacing, overrides)
   };
 }
 function aliasEdgeMap(graph) {
@@ -5304,7 +5358,8 @@ function assignInstallNames(graph, artifacts) {
     decisions.set(decisionKey(updated), namespaceDecision(updated, "alias"));
     return updated;
   });
-  const collisionGroups = [...groupBy(withAliases, (artifact) => `${artifact.type}\0${artifact.installName}`).values()].filter((group) => group.length > 1);
+  const { artifacts: withOverrides, overrides } = applyWorkspaceOverrides(graph, withAliases);
+  const collisionGroups = [...groupBy(withOverrides, (artifact) => `${artifact.type}\0${artifact.installName}`).values()].filter((group) => group.length > 1);
   const toRename = /* @__PURE__ */ new Set();
   for (const group of collisionGroups) {
     if (group.some((artifact) => decisions.has(decisionKey(artifact)))) throw installNameCollisionError(group);
@@ -5315,11 +5370,11 @@ function assignInstallNames(graph, artifacts) {
     }
   }
   const used = /* @__PURE__ */ new Map();
-  for (const artifact of withAliases) {
+  for (const artifact of withOverrides) {
     if (toRename.has(artifact)) continue;
     used.set(`${artifact.type}\0${artifact.installName}`, artifact);
   }
-  const out = withAliases.filter((artifact) => !toRename.has(artifact));
+  const out = withOverrides.filter((artifact) => !toRename.has(artifact));
   for (const group of groupBy([...toRename], (artifact) => `${artifact.type}\0${artifact.name}`).values()) {
     const renamed = namespaceTransitiveGroup(group, used);
     for (const artifact of renamed) {
@@ -5328,7 +5383,52 @@ function assignInstallNames(graph, artifacts) {
       out.push(artifact);
     }
   }
-  return { artifacts: out, namespacing: [...decisions.values()] };
+  const finalInstallNames = new Map(out.map((artifact) => [decisionKey(artifact), artifact.installName]));
+  const finalOverrides = overrides.map((override) => ({
+    ...override,
+    installName: finalInstallNames.get(`${override.graphNodeId}\0${override.type}\0${override.name}`) ?? override.installName
+  }));
+  return { artifacts: out, namespacing: [...decisions.values()], overrides: finalOverrides };
+}
+function applyWorkspaceOverrides(graph, artifacts) {
+  const directives = workspaceOverrides(graph);
+  if (directives.length === 0) return { artifacts, overrides: [] };
+  const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
+  let remaining = [...artifacts];
+  const decisions = [];
+  for (const directive of directives) {
+    const matched = remaining.filter((artifact) => overrideMatchesArtifact(directive.selector, artifact, nodeById.get(artifact.graphNodeId)));
+    const losers = matched.filter((artifact) => !directive.reachable.has(artifact.graphNodeId));
+    if (matched.length === 0) {
+      throw new Error(`Workspace override ${directive.selector} from ${directive.rootId} did not match any rendered artifact.`);
+    }
+    if (losers.length === 0) {
+      throw new Error(`Workspace override ${directive.selector} from ${directive.rootId} matched only artifacts inside the replacing root.`);
+    }
+    if (losers.length > 1) {
+      throw new Error(`Workspace override ${directive.selector} from ${directive.rootId} matched multiple artifacts: ${losers.map((artifact) => artifact.logicalSelector).sort().join(", ")}`);
+    }
+    const loser = losers[0];
+    const winners = remaining.filter((artifact) => artifact !== loser && directive.reachable.has(artifact.graphNodeId) && artifact.type === loser.type && artifact.name === loser.name);
+    if (winners.length === 0) {
+      throw new Error(`Workspace override ${directive.selector} from ${directive.rootId} has no selected replacement for ${loser.type}/${loser.name}.`);
+    }
+    if (winners.length > 1) {
+      throw new Error(`Workspace override ${directive.selector} from ${directive.rootId} has multiple selected replacements for ${loser.type}/${loser.name}: ${winners.map((artifact) => artifact.logicalSelector).sort().join(", ")}`);
+    }
+    const winner = winners[0];
+    remaining = remaining.filter((artifact) => artifact !== loser);
+    decisions.push({
+      rootId: directive.rootId,
+      selector: directive.selector,
+      graphNodeId: winner.graphNodeId,
+      overriddenGraphNodeId: loser.graphNodeId,
+      type: winner.type,
+      name: winner.name,
+      installName: winner.installName
+    });
+  }
+  return { artifacts: remaining, overrides: decisions };
 }
 function namespaceTransitiveGroup(group, used) {
   const sorted = [...group].sort((a, b) => a.logicalSelector.localeCompare(b.logicalSelector));
@@ -5366,6 +5466,16 @@ function workspaceAliases(graph) {
   }
   return aliases;
 }
+function workspaceOverrides(graph) {
+  const overrides = [];
+  for (const root of graph.roots) {
+    const reachable = reachableNodeIds(graph, root.graphNodeId);
+    for (const selector of root.overrides ?? []) {
+      overrides.push({ rootId: root.rootId, selector, reachable });
+    }
+  }
+  return overrides;
+}
 function validateAliasScopes(graph, artifacts, aliases) {
   for (const alias of aliases) {
     const matching = artifacts.filter((artifact) => {
@@ -5382,6 +5492,35 @@ function aliasMatchesArtifact(selector, artifact, node) {
   const artifactSelector = `${artifact.type}/${artifact.name}`;
   return selector === `${artifact.graphNodeId}:${artifactSelector}` || node !== void 0 && selector === `${node.name}@${node.version}:${artifactSelector}` || node !== void 0 && selector === `${node.name}:${artifactSelector}`;
 }
+function overrideMatchesArtifact(selector, artifact, node) {
+  const sourceSeparator = selector.lastIndexOf("::");
+  if (sourceSeparator >= 0) {
+    const sourceSelector = selector.slice(0, sourceSeparator).trim();
+    const artifactSelector = selector.slice(sourceSeparator + 2).trim();
+    return artifactSelector === `${artifact.type}/${artifact.name}` && sourceMatchesArtifact(sourceSelector, node);
+  }
+  return aliasMatchesArtifact(selector, artifact, node);
+}
+function sourceMatchesArtifact(selector, node) {
+  if (!node || selector.length === 0) return false;
+  if (selector === node.source || selector === node.normalizedSource || selector === node.name || selector === node.id) return true;
+  const normalized = node.normalizedSource.toLowerCase();
+  const source = node.source.toLowerCase();
+  const value = selector.toLowerCase();
+  if (value === source || value === normalized || value === node.name.toLowerCase() || value === node.id.toLowerCase()) return true;
+  const github = /^github:([^#]+?)(?:#(.+))?$/.exec(value);
+  if (github) {
+    const repo = github[1].replace(/\.git$/i, "");
+    const ref = github[2];
+    const prefix = `git:https://github.com/${repo}.git#`;
+    return ref ? normalized.includes(`${prefix}${ref}`) : normalized.includes(prefix);
+  }
+  if (!value.includes(":") && value.includes("/")) {
+    const repo = value.replace(/\.git$/i, "");
+    return normalized.includes(`github.com/${repo}.git#`) || source.includes(`github.com/${repo}.git`);
+  }
+  return false;
+}
 function reachableNodeIds(graph, rootNodeId) {
   const reachable = /* @__PURE__ */ new Set();
   const queue = [rootNodeId];
@@ -5743,7 +5882,8 @@ async function syncProfile(options) {
         mode: options.mode ?? pkg.mode,
         ref: pkg.requestedRef,
         select: selected ?? normalizeArtifactSelectors(pkg.select, pkg.skills),
-        aliases: pkg.aliases
+        aliases: pkg.aliases,
+        overrides: pkg.overrides
       })),
       targetRoot: target.targetRoot,
       workspaceRoot: options.workspaceRoot,
@@ -6246,7 +6386,7 @@ 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());
 });
-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, or vercel-skills)").option("--adapter <adapter>", "built-in adapter", "openclaw").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("--target-root <path>", "workspace root", process.cwd()).option("--mode <mode>", "pinned or tracking", "pinned").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, []).action(async (source, options) => {
+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, or vercel-skills)").option("--adapter <adapter>", "built-in adapter", "openclaw").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("--target-root <path>", "workspace root", process.cwd()).option("--mode <mode>", "pinned or tracking", "pinned").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("--override <source-or-package::type/name>", "allow this package to replace a colliding artifact (repeatable)", collectOverrideOption, []).action(async (source, options) => {
   const targetRoot = normalizeTargetRoot(options.targetRoot);
   const entry = await packageEntryFromSource(source, targetRoot, options);
   await writeWorkspaceConfig(targetRoot, upsertPackage(await readWorkspaceConfig(targetRoot), entry));
@@ -6278,13 +6418,13 @@ program.command("scan").description("scan a package source for validation findin
   }
   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").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("--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("--dry-run", "accepted for symmetry; plan never writes", 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("--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").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("--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("--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("--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("--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").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("--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("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--execute-plugins", "execute semantic plugin installs", 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("--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").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("--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("--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("--execute-plugins", "execute semantic plugin installs", 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("--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("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").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("--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("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--execute-plugins", "execute semantic plugin installs", 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("--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").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("--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("--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("--execute-plugins", "execute semantic plugin installs", 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("--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 });
 });
@@ -6304,6 +6444,9 @@ program.command("deps").description("inspect the OpenPack dependency graph").add
           for (const decision of result.bundle.graphLock.canonical.namespacing) {
             console.log(`NAMESPACE ${decision.graphNodeId}:${decision.type}/${decision.name} -> ${decision.type}/${decision.installName} (${decision.reason})`);
           }
+          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 rm9(result.bundle.root, { recursive: true, force: true });
         }
         continue;
@@ -6520,7 +6663,8 @@ async function packageEntryFromSource(source, targetRoot, options) {
       adapterCodeHash: adapter.programmatic?.hash,
       mode: options.mode ?? "pinned",
       requestedRef: bundle.source.requestedRef,
-      select: selectedArtifacts
+      select: selectedArtifacts,
+      overrides: overrideArtifactsFromOptions(options)
     };
   } finally {
     await rm9(bundle.root, { recursive: true, force: true });
@@ -6642,6 +6786,7 @@ async function buildGraphPlansForTarget(target, source, options, behavior) {
           ref: pkg.requestedRef,
           select: selectedArtifacts ?? normalizeArtifactSelectors(pkg.select, pkg.skills),
           aliases: pkg.aliases,
+          overrides: pkg.overrides,
           useLock: behavior.mode === "install" ? true : !updateThisPackage
         };
       }),
@@ -6822,7 +6967,8 @@ async function uninstallConfiguredPackage(target, packageName, options) {
           mode: pkg2.mode,
           ref: pkg2.requestedRef,
           select: normalizeArtifactSelectors(pkg2.select, pkg2.skills),
-          aliases: pkg2.aliases
+          aliases: pkg2.aliases,
+          overrides: pkg2.overrides
         })),
         targetRoot: remainingGroup.target.targetRoot,
         workspaceRoot: remainingGroup.target.workspaceRoot,
@@ -6985,9 +7131,16 @@ function collectSkillOption(value, previous) {
 function collectTrustOption(value, previous) {
   return [...previous, value];
 }
+function collectOverrideOption(value, previous) {
+  return [...previous, ...splitSelectorList(value)];
+}
 function selectedArtifactsFromOptions(options) {
   return normalizeArtifactSelectors(options.select, options.skills ?? options.skill);
 }
+function overrideArtifactsFromOptions(options) {
+  const values = options.overrides ?? options.override;
+  return values && values.length > 0 ? values : void 0;
+}
 function filterUninstallPlanBySelection(plan, selected) {
   if (!selected?.length) return plan;
   const requested = normalizeArtifactSelectors(selected) ?? [];
@@ -7108,7 +7261,9 @@ async function main() {
   });
   await program.parseAsync();
 }
-main().catch((error) => {
+try {
+  await main();
+} catch (error) {
   console.error(error instanceof Error ? error.message : String(error));
   process.exitCode = 1;
-});
+}

package/openpack.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "name": "NestDevLab/agentwheel",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "provides": [
     { "type": "skills", "path": "skills", "required": true }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",

package/skills/agentwheel/SKILL.md

@@ -141,6 +141,34 @@ agentwheel add github:owner/repo --select skills/code-review --select rules/core
 agentwheel add github:owner/repo --select skills/code-review,rules/core.md
 ```
 
+Use a source override when a selected package should replace the same artifact coming from another
+source, such as a forked skill overriding a meta-pack dependency. The declaration is explicit and
+planning fails if it does not match exactly one losing artifact and one selected replacement:
+
+```bash
+agentwheel add github:Yehonal/agent-toolkit#main \
+  --skill self-improve \
+  --override 'github:FrancescoBorzi/agent-toolkit::skills/self-improve'
+```
+
+Equivalent config:
+
+```json
+{
+  "name": "agent-toolkit-nestdev",
+  "source": "github:Yehonal/agent-toolkit#main",
+  "driver": "git",
+  "adapter": "codex",
+  "mode": "tracking",
+  "select": ["skills/self-improve"],
+  "overrides": ["github:FrancescoBorzi/agent-toolkit::skills/self-improve"]
+}
+```
+
+`source::type/name` identifies the artifact being replaced. `github:owner/repo` matches any ref
+for that repo; include `#main` or another ref to narrow it. Review `OVERRIDE` lines in
+`agentwheel plan`, `agentwheel deps tree`, or `agentwheel deps why` before applying fleet-wide.
+
 Use `--name` for a stable local alias:
 
 ```bash
@@ -289,7 +317,9 @@ Drift means a managed runtime output changed outside agentwheel. Fix drift by ch
 
 - Layer local instructions with `agentwheel remember`.
 - Add separate local artifacts under `.agentwheel/additions`.
-- Override an upstream item under `.agentwheel/overrides`.
+- Override upstream content under `.agentwheel/overrides`.
+- Override source precedence with package `overrides` when a forked source should replace a
+  colliding upstream artifact.
 - Eject an item into `.agentwheel/ejected` when the user wants local ownership.
 
 Append durable local instruction text: