agentwheel 0.9.0 → 0.11.0

package/README.md

@@ -7,7 +7,7 @@
 <p align="center"><strong>One source. Every agent.</strong></p>
 
 <p align="center">
-  Weave your skills, rules, and instructions across every AI agent you use,
+  Weave skills, rules, instructions, commands, subagents, MCP, hooks, settings, and plugins across every AI agent you use,
   from any source, reconciled into each runtime with your private tweaks intact.
 </p>
 
@@ -15,8 +15,9 @@
 
 ## Why agentwheel?
 
-Your AI agents are multiplying. Claude here, Codex there, custom runtimes elsewhere, and each one
-wants skills, rules, instructions, commands, MCP, hooks, and settings in its own native shape.
+Your AI agents are multiplying. OpenClaw, Claude Code, Codex CLI, Copilot, Hermes — and the next
+harness your team adopts. Each one wants its own skills, rules, instructions, commands, subagents,
+MCP servers, hooks, and settings, in its own layout.
 
 **agentwheel makes that one declared state.** Add packages to `.agentwheel/config.json`, preview the
 runtime changes, then install the declared state into each target. Updates move tracking sources
@@ -33,9 +34,23 @@ 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
+
+agentwheel installs OpenPack resources into five built-in runtimes and into custom harnesses:
+
+- **OpenClaw** — `.openclaw/`
+- **Claude Code** — `.claude/`
+- **Codex CLI** — `.codex/`
+- **GitHub Copilot** — `.github/`
+- **Hermes** — `.hermes/`
+- **Bring your own** — JSONC config adapters with `--adapter-config`, or programmatic adapters with `--adapter-module`
+
+Supported resource types include instructions, rules, skills, commands, subagents, MCP, hooks,
+settings, plugins, and fragments; see the full per-runtime target table below.
 
 ## Core Commands
 
@@ -133,6 +148,7 @@ For a control-plane setup, define named agents in config. Global config lives at
 agentwheel install --agent lab-openclaw
 agentwheel install --all
 agentwheel install --profile daily
+agentwheel install --all-detected
 ```
 
 SSH targets use the same manifest and drift model as local targets. Planning reads the remote
@@ -146,7 +162,9 @@ agentwheel init --fleet-example
 ```
 
 Target resolution order is exact: `--target-root` wins, then `--agent`, then auto-detect from the
-current directory, then fallback to the current directory.
+current directory, then fallback to the current directory. `--all-detected` is an explicit escape hatch
+for applying to every runtime marker found in the current directory or `--target-root`; `--all` remains
+reserved for configured agents.
 
 ## Core Ideas
 
@@ -254,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
@@ -267,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
@@ -290,15 +362,21 @@ published:
 agentwheel install ./my-pack --adapter-config ./myco-internal.jsonc
 ```
 
+For adapter behavior that needs code, load a programmatic adapter module:
+
+```bash
+agentwheel install ./my-pack --adapter-module ./myco-adapter.js
+```
+
 Built-in runtime targets:
 
 | Runtime | Main targets |
 |---|---|
-| **OpenClaw** | `.openclaw/AGENTS.md`, `.openclaw/skills`, `.openclaw/rules`, `.openclaw/commands`, MCP/hooks/settings, semantic plugin planning |
+| **OpenClaw** | `.openclaw/AGENTS.md`, `.openclaw/skills`, `.openclaw/rules`, `.openclaw/commands`, `.openclaw/agents`, MCP/hooks/settings, semantic plugin planning |
 | **Claude Code** | `.claude/CLAUDE.md`, `.claude/skills`, `.claude/commands`, `.claude/agents`, `.claude/rules`, `.claude/.mcp.json`, `.claude/settings.json` |
 | **Codex CLI** | `.codex/AGENTS.md`, `.codex/skills`, `.codex/commands`, `.codex/agents`, `.codex/rules`, `.codex/config.toml`, `.codex/hooks.json` |
-| **Hermes** | `.hermes/AGENTS.md`, `.hermes/skills`, `.hermes/rules`, `.hermes/commands`, MCP/hooks/settings |
-| **GitHub Copilot** | `.github/copilot-instructions.md`, `.github/instructions`, `.github/prompts` |
+| **Hermes** | `.hermes/AGENTS.md`, `.hermes/skills`, `.hermes/rules`, `.hermes/commands`, `.hermes/agents`, MCP/hooks/settings |
+| **GitHub Copilot** | `.github/copilot-instructions.md`, `.github/instructions`, `.github/prompts`, `.github/skills`, `.github/agents`, `.vscode/mcp.json` |
 
 ## Docs
 

package/dist/index.js

@@ -9,7 +9,7 @@ import {
 
 // src/cli/index.ts
 import { mkdir as mkdir14, rm as rm9, writeFile as writeFile12 } from "fs/promises";
-import { dirname as dirname21, join as join28, resolve as resolve17 } from "path";
+import { dirname as dirname21, join as join28, resolve as resolve18 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command } from "commander";
 
@@ -131,9 +131,9 @@ var copilotAdapter = {
     instructions: { enabled: true, dest: ".github/copilot-instructions.md" },
     rules: { enabled: true, dest: ".github/instructions" },
     commands: { enabled: true, dest: ".github/prompts" },
-    // GitHub Copilot has no native SKILL.md runtime surface; keep skills disabled
-    // until a conversion target is introduced.
-    skills: { enabled: false, dest: ".github/skills" }
+    skills: { enabled: true, dest: ".github/skills" },
+    subagents: { enabled: true, dest: ".github/agents" },
+    mcp: { enabled: true, dest: ".vscode/mcp.json", merge: "json-deep" }
   }
 };
 
@@ -162,6 +162,7 @@ var hermesAdapter = {
     rules: { enabled: true, dest: ".hermes/rules" },
     skills: { enabled: true, dest: ".hermes/skills" },
     commands: { enabled: true, dest: ".hermes/commands" },
+    subagents: { enabled: true, dest: ".hermes/agents" },
     mcp: { enabled: true, dest: ".hermes/mcp", merge: "json-deep" },
     hooks: { enabled: true, dest: ".hermes/hooks", merge: "json-deep" },
     settings: { enabled: true, dest: ".hermes/settings.json", merge: "json-deep" }
@@ -177,6 +178,7 @@ var openClawAdapter = {
     rules: { enabled: true, dest: ".openclaw/rules" },
     skills: { enabled: true, dest: ".openclaw/skills" },
     commands: { enabled: true, dest: ".openclaw/commands" },
+    subagents: { enabled: true, dest: ".openclaw/agents" },
     mcp: { enabled: true, dest: ".openclaw/mcp", merge: "json-deep" },
     hooks: { enabled: true, dest: ".openclaw/hooks", merge: "json-deep" },
     settings: { enabled: true, dest: ".openclaw/settings.json", merge: "json-deep" },
@@ -295,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),
@@ -344,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),
@@ -352,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({
@@ -382,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),
@@ -393,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}`))
     }
   };
@@ -542,13 +560,13 @@ async function spawnWithInput(command, args, input) {
   if (result.stderr) throw new Error(result.stderr);
 }
 function waitForProcess(child, label) {
-  return new Promise((resolve18, reject) => {
+  return new Promise((resolve19, reject) => {
     const stderr = [];
     child.stderr?.on("data", (chunk) => stderr.push(chunk));
     child.on("error", reject);
     child.on("close", (code) => {
       const message = Buffer.concat(stderr).toString("utf8");
-      if (code === 0) resolve18({ stderr: "" });
+      if (code === 0) resolve19({ stderr: "" });
       else reject(new Error(`${label} exited ${code}${message ? `: ${message}` : ""}`));
     });
   });
@@ -654,6 +672,7 @@ import { resolve as resolve3 } from "path";
 // src/model/manifest.ts
 import { z as z4 } from "zod";
 var dependencyRoleSchema = z4.enum(["root", "direct", "transitive", "fragment"]);
+var legacyUnownedWorkspaceOwner = "legacy:unowned";
 var manifestEntryV1Schema = z4.object({
   path: z4.string().min(1),
   artifactType: artifactTypeSchema,
@@ -676,6 +695,7 @@ var manifestEntrySchema = manifestEntryV1Schema.extend({
   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()
 }).transform((entry) => {
   const owners = [...new Set(entry.owners)].sort();
@@ -1388,6 +1408,7 @@ function manifestEntryForOperation(operation, values) {
     dependencyRole: operation.dependencyRole ?? "root",
     owners,
     refCount: owners.length,
+    workspaceOwner: operation.workspaceOwner ?? "workspace:unknown",
     kind: operation.kind,
     hash: values.hash,
     sourceHash: values.sourceHash,
@@ -1476,6 +1497,10 @@ async function createCombinedInstallPlan(desiredArtifacts, adapter, targetRoot,
   return createPlanFromOperations(desired, adapter, targetRoot, manifest, transport, options);
 }
 async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifest, transport, options) {
+  const workspaceOwner = options.workspaceOwner;
+  if (workspaceOwner) {
+    for (const op of desiredOps) op.workspaceOwner = workspaceOwner;
+  }
   for (const op of desiredOps) assertOperationContained(op, targetRoot);
   const migration = await migrateManifestForPlan(manifest, desiredOps, targetRoot, transport);
   const effectiveEntries = migration.entries;
@@ -1518,6 +1543,12 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
       continue;
     }
     const existing = manifestByPath.get(op.relativeDestPath);
+    if (existing && workspaceOwner && !entryOwnedByWorkspace(existing, workspaceOwner)) {
+      if (!await canAdoptLegacyUnownedEntry(existing, op, transport)) {
+        operations.push(keepForeignManifestEntryOperation(existing, targetRoot, workspaceOwner, op));
+        continue;
+      }
+    }
     const exists = await transport.pathExists(op.destPath);
     if (!exists) {
       operations.push({ ...op, action: "create", reason: "destination missing" });
@@ -1559,6 +1590,10 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
     const destPath = join5(targetRoot, entry.path);
     if (!await transport.pathExists(destPath)) continue;
     const currentHash = await transport.hashPath(destPath);
+    if (workspaceOwner && !entryOwnedByWorkspace(entry, workspaceOwner)) {
+      operations.push(keepForeignManifestEntryOperation(entry, targetRoot, workspaceOwner, void 0, currentHash));
+      continue;
+    }
     if (currentHash !== entry.hash) {
       operations.push({
         action: "drift",
@@ -1714,6 +1749,16 @@ function operationMatchesManifestEntry(op, entry) {
   if ("graphNodeId" in entry && entry.graphNodeId && op.graphNodeId && entry.graphNodeId === op.graphNodeId) return true;
   return op.packageName !== void 0 && entry.packageName === op.packageName;
 }
+function entryOwnedByWorkspace(entry, workspaceOwner) {
+  return "workspaceOwner" in entry && entry.workspaceOwner === workspaceOwner;
+}
+async function canAdoptLegacyUnownedEntry(entry, op, transport) {
+  if (!("workspaceOwner" in entry) || entry.workspaceOwner !== legacyUnownedWorkspaceOwner) return false;
+  if (entry.artifactType !== op.artifactType || entry.kind !== op.kind) return false;
+  if (!op.desiredHash || entry.sourceHash !== op.desiredHash) return false;
+  if (!await transport.pathExists(op.destPath)) return false;
+  return await transport.hashPath(op.destPath) === entry.hash;
+}
 function collisionOperation(op, group, incumbent) {
   const owners = group.map(describeOperationOwner).sort();
   const incumbentText = incumbent ? `; incumbent ${describeOperationOwner(incumbent)} keeps the plain name` : "";
@@ -1737,6 +1782,7 @@ function adoptLegacyEntry(entry, op) {
     dependencyRole: op.dependencyRole ?? "root",
     owners,
     refCount: owners.length,
+    workspaceOwner: op.workspaceOwner ?? legacyUnownedWorkspaceOwner,
     graphLockDigest: op.graphLockDigest,
     composedFrom: op.composedFrom ?? entry.composedFrom
   };
@@ -1759,6 +1805,7 @@ function operationMetadataFromEntry(entry) {
       graphNodeId: entry.graphNodeId,
       dependencyRole: entry.dependencyRole,
       owners: entry.owners,
+      workspaceOwner: entry.workspaceOwner,
       graphLockDigest: entry.graphLockDigest
     };
   }
@@ -1766,7 +1813,31 @@ function operationMetadataFromEntry(entry) {
     installName: entry.artifactName,
     logicalSelector: `${entry.artifactType}/${entry.artifactName}`,
     dependencyRole: "root",
-    owners: [entry.packageName ?? "legacy"]
+    owners: [entry.packageName ?? "legacy"],
+    workspaceOwner: legacyUnownedWorkspaceOwner
+  };
+}
+function keepForeignManifestEntryOperation(entry, targetRoot, workspaceOwner, operation, currentHash) {
+  const owner = "workspaceOwner" in entry ? entry.workspaceOwner : legacyUnownedWorkspaceOwner;
+  return {
+    action: "keep",
+    artifactType: entry.artifactType,
+    artifactName: entry.artifactName,
+    kind: entry.kind,
+    destPath: operation?.destPath ?? join5(targetRoot, entry.path),
+    relativeDestPath: entry.path,
+    desiredHash: entry.sourceHash,
+    currentHash: currentHash ?? operation?.currentHash ?? entry.hash,
+    manifestHash: entry.hash,
+    reason: `foreign artifact owned by ${owner}; kept outside workspace ${workspaceOwner}`,
+    channel: entry.channel,
+    packageName: entry.packageName,
+    semanticCommand: entry.semanticCommand,
+    execute: entry.executed,
+    mergeStrategy: entry.mergeStrategy,
+    composedFrom: entry.composedFrom,
+    preserveInManifest: true,
+    ...operationMetadataFromEntry(entry)
   };
 }
 function normalizeOperationOwners(op) {
@@ -2083,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);
@@ -2120,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) {
@@ -2142,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) {
@@ -2714,7 +2794,7 @@ async function withFilesystemLock(lockPath, timeoutMs, fn) {
       if (Date.now() - started > timeoutMs) {
         throw new Error(`Timed out waiting for git cache lock at ${lockPath}`);
       }
-      await new Promise((resolve18) => setTimeout(resolve18, 50));
+      await new Promise((resolve19) => setTimeout(resolve19, 50));
     }
   }
   try {
@@ -3721,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(),
@@ -4260,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,
@@ -4291,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,
@@ -4299,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,
@@ -4311,6 +4394,7 @@ function createGraphLock(graph, artifacts = [], targetFingerprint, includeEdges
       includeEdges,
       artifacts,
       namespacing,
+      overrides,
       plainNameIncumbents: []
     }
   };
@@ -4318,13 +4402,33 @@ function createGraphLock(graph, artifacts = [], targetFingerprint, includeEdges
 async function processRequirement(requirement, options, fetchCache, nodesByKey, rootResults, edgeMap) {
   try {
     const lockLabel = options.offline ? "Offline" : options.frozenLock ? "Frozen lock" : "Locked install";
-    const lockedByReference = lockedNodeForRequirementReference(requirement, options, lockLabel);
-    const normalized = lockedByReference ? normalizedSourceFromLockedNode(lockedByReference.node) : await normalizeDependencySource(requirement.source, {
+    let lockedByReference = lockedNodeForRequirementReference(requirement, options, lockLabel);
+    let normalized = lockedByReference ? normalizedSourceFromLockedNode(lockedByReference.node) : await normalizeDependencySource(requirement.source, {
       declaringPackageRoot: requirement.declaringPackageRoot,
       workspaceRoot: options.workspaceRoot,
       ref: requirement.ref,
       registryClient: options.registryClient
     });
+    if (lockedByReference && shouldCheckLockedRootSource(requirement)) {
+      const declared = await normalizeDependencySource(requirement.source, {
+        declaringPackageRoot: requirement.declaringPackageRoot,
+        workspaceRoot: options.workspaceRoot,
+        ref: requirement.ref,
+        registryClient: options.registryClient
+      });
+      if (lockedRootSourceDrifted(declared, lockedByReference.node)) {
+        if (options.frozenLock || options.offline) {
+          throw new Error(
+            `${lockLabel} root '${requirement.rootId}' source differs from declared source:
+- declared: ${declared.normalizedSource}
+- locked: ${lockedByReference.node.normalizedSource}
+Run without ${lockLabel === "Offline" ? "--offline" : "--frozen-lock"} first.`
+          );
+        }
+        lockedByReference = void 0;
+        normalized = declared;
+      }
+    }
     const frozen = lockedByReference ?? lockedNodeForRequirement(normalized.normalizedSource, requirement, options, lockLabel);
     let fetched;
     try {
@@ -4387,7 +4491,8 @@ async function processRequirement(requirement, options, fetchCache, nodesByKey,
         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) {
@@ -4747,6 +4852,18 @@ function lockedNodeForRequirementReference(requirement, options, label) {
     requestedRef: node.driver === "git" ? node.resolvedCommit ?? node.requestedRef : node.requestedRef
   };
 }
+function shouldCheckLockedRootSource(requirement) {
+  if (!requirement.useLock) return false;
+  if (requirement.depth !== 0 || !requirement.rootId) return false;
+  return isExplicitNonRegistrySource(requirement.source);
+}
+function isExplicitNonRegistrySource(source) {
+  const trimmed = source.trim();
+  return trimmed === "~" || trimmed.startsWith("~/") || trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith("/") || trimmed.startsWith("local:") || trimmed.startsWith("github:") || trimmed.startsWith("git:") || trimmed.startsWith("skillkit:") || trimmed.startsWith("vercel:");
+}
+function lockedRootSourceDrifted(declared, locked) {
+  return declared.normalizedSource !== locked.normalizedSource || declared.requestedRef !== locked.requestedRef;
+}
 function normalizedSourceFromLockedNode(node) {
   return {
     source: node.source,
@@ -4765,8 +4882,8 @@ function verifyIntegrity(integrity, sourceHash, label) {
 async function withCachePathLock(path, fn) {
   const previous = cacheLocks.get(path) ?? Promise.resolve();
   let release = () => void 0;
-  const current = previous.then(() => new Promise((resolve18) => {
-    release = resolve18;
+  const current = previous.then(() => new Promise((resolve19) => {
+    release = resolve19;
   }));
   cacheLocks.set(path, current);
   await previous;
@@ -4974,7 +5091,7 @@ import { rm as rm8 } from "fs/promises";
 // src/lifecycle/source-plan.ts
 import { createHash as createHash6 } from "crypto";
 import { mkdir as mkdir12 } from "fs/promises";
-import { dirname as dirname17, join as join22 } from "path";
+import { dirname as dirname17, join as join22, resolve as resolve14 } from "path";
 
 // src/resolve/graph-diff.ts
 function diffGraphLocks(previous, next) {
@@ -4982,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) {
@@ -5044,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}`;
 }
@@ -5063,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);
 }
@@ -5167,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) {
@@ -5217,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);
@@ -5228,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) {
@@ -5241,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));
@@ -5279,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) => {
@@ -5295,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];
@@ -5512,7 +5738,8 @@ async function createGraphSourcePlan(options) {
   const manifest = await readInstallManifest(options.targetRoot, options.adapter.name, transport);
   const plan = await createCombinedInstallPlan(desiredArtifacts, options.adapter, options.targetRoot, manifest, transport, {
     baseRevision: manifest?.revision ?? null,
-    graphLockDigest
+    graphLockDigest,
+    workspaceOwner: workspaceOwnerId(workspaceRoot)
   });
   return {
     plan,
@@ -5570,6 +5797,9 @@ function sanitizePathSegment(value) {
 function digestGraphLock(lock) {
   return createHash6("sha256").update(canonicalGraphLockJson(lock)).digest("hex");
 }
+function workspaceOwnerId(workspaceRoot) {
+  return `workspace-root:${resolve14(workspaceRoot)}`;
+}
 function assertFrozenGraph(previousLock, graph, frozen, label) {
   if (!frozen) return;
   if (!previousLock) {
@@ -5652,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,
@@ -5743,7 +5974,7 @@ async function packageFromSource(source, options) {
 }
 
 // src/runtime/target.ts
-import { basename as basename12, dirname as dirname18, join as join23, resolve as resolve14 } from "path";
+import { basename as basename12, dirname as dirname18, join as join23, resolve as resolve15 } from "path";
 var runtimeMarkers = [
   { adapter: "openclaw", dirs: [".openclaw", ".clawdbot", ".moltbot"] },
   { adapter: "claude", dirs: [".claude"] },
@@ -5752,9 +5983,9 @@ var runtimeMarkers = [
   { adapter: "copilot", dirs: [".github"] }
 ];
 async function resolveRuntimeTarget(request = {}) {
-  const cwd = resolve14(request.cwd ?? process.cwd());
+  const cwd = resolve15(request.cwd ?? process.cwd());
   if (request.targetRoot) {
-    const targetRoot = resolve14(request.targetRoot);
+    const targetRoot = resolve15(request.targetRoot);
     return {
       adapter: request.adapter ?? "openclaw",
       targetRoot,
@@ -5783,7 +6014,7 @@ async function resolveRuntimeTarget(request = {}) {
 async function resolveAllRuntimeTargets(request = {}) {
   if (request.targetRoot) return [await resolveRuntimeTarget(request)];
   if (request.agent) return [await resolveRuntimeTarget(request)];
-  const cwd = resolve14(request.cwd ?? process.cwd());
+  const cwd = resolve15(request.cwd ?? process.cwd());
   const workspaceRoot = await findWorkspaceRoot(cwd);
   const config = await readMergedWorkspaceConfig(workspaceRoot, { globalRoot: request.globalRoot });
   const targets = Object.entries(config.agents).map(([name]) => targetFromAgent(name, config, workspaceRoot));
@@ -5792,8 +6023,29 @@ async function resolveAllRuntimeTargets(request = {}) {
   }
   return targets;
 }
+async function resolveAllDetectedRuntimeTargets(request = {}) {
+  if (request.agent) return [await resolveRuntimeTarget(request)];
+  const scanRoot = runtimeScanRoot(request);
+  const matches = await detectRuntimeTargets(scanRoot, request.adapter);
+  if (matches.length === 0) {
+    throw new Error(`No runtime directories detected at ${scanRoot}. Pass --target-root or --agent.`);
+  }
+  return Promise.all(matches.map(async (match) => ({
+    ...match,
+    workspaceRoot: await findWorkspaceRoot(match.targetRoot),
+    transport: "local",
+    source: "auto-detect"
+  })));
+}
 async function detectRuntimeTarget(cwd = process.cwd(), adapterFilter) {
-  const root = resolve14(cwd);
+  const unique = await detectRuntimeTargets(cwd, adapterFilter);
+  if (unique.length > 1) {
+    throw new Error(`Multiple runtime directories detected: ${unique.map((item) => `${item.adapter} at ${item.targetRoot}`).join(", ")}. Pass --adapter, --agent, or --all-detected.`);
+  }
+  return unique[0];
+}
+async function detectRuntimeTargets(cwd = process.cwd(), adapterFilter) {
+  const root = resolve15(cwd);
   const matches = [];
   for (const marker of runtimeMarkers) {
     if (adapterFilter && marker.adapter !== adapterFilter) continue;
@@ -5805,11 +6057,7 @@ async function detectRuntimeTarget(cwd = process.cwd(), adapterFilter) {
       }
     }
   }
-  const unique = dedupeTargets(matches);
-  if (unique.length > 1) {
-    throw new Error(`Multiple runtime directories detected: ${unique.map((item) => `${item.adapter} at ${item.targetRoot}`).join(", ")}. Pass --adapter or --agent.`);
-  }
-  return unique[0];
+  return dedupeTargets(matches);
 }
 function targetFromAgent(name, config, workspaceRoot) {
   const agent = config.agents[name];
@@ -5838,6 +6086,11 @@ function dedupeTargets(matches) {
   }
   return [...byKey.values()];
 }
+function runtimeScanRoot(request) {
+  const root = resolve15(request.targetRoot ?? request.cwd ?? process.cwd());
+  if (request.targetRoot) return root;
+  return runtimeMarkers.some((marker) => marker.dirs.includes(basename12(root))) ? dirname18(root) : root;
+}
 
 // src/cli/update-check.ts
 import { mkdir as mkdir13, readFile as readFile16, writeFile as writeFile10 } from "fs/promises";
@@ -5919,9 +6172,9 @@ function normalizeVersion(version) {
 
 // src/model/package-validate.ts
 import { stat as stat11 } from "fs/promises";
-import { resolve as resolve15 } from "path";
+import { resolve as resolve16 } from "path";
 async function validatePackage(root) {
-  const packageRoot = resolve15(root);
+  const packageRoot = resolve16(root);
   const findings = [];
   const manifestPath = await findPackageManifestPath(packageRoot);
   if (!manifestPath) {
@@ -5989,7 +6242,7 @@ async function validateManifestComposeInclude(packageRoot, selector, optional, f
   try {
     validateSelector(selector, "compose.include", findings, manifestPath, { fragmentsOnly: true, aliases });
     if (isCrossPackageSelector(selector)) return;
-    const full = resolve15(packageRoot, selector);
+    const full = resolve16(packageRoot, selector);
     if (full !== packageRoot && !full.startsWith(`${packageRoot}/`)) {
       findings.push({ level: "error", message: `Compose include escapes package root: ${selector}`, path: manifestPath });
       return;
@@ -6043,10 +6296,10 @@ function isCrossPackageSelector(value) {
 
 // src/model/package-migrate.ts
 import { readFile as readFile17, rename as rename4, writeFile as writeFile11 } from "fs/promises";
-import { join as join26, resolve as resolve16 } from "path";
+import { join as join26, resolve as resolve17 } from "path";
 import { applyEdits, modify, parse as parse3 } from "jsonc-parser";
 async function migratePackageManifest(root) {
-  const packageRoot = resolve16(root);
+  const packageRoot = resolve17(root);
   for (const name of openPackManifestNames) {
     const path = join26(packageRoot, name);
     if (await pathExists(path)) {
@@ -6133,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));
@@ -6165,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("--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("--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("--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 });
 });
@@ -6191,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;
@@ -6345,7 +6601,7 @@ async function runInstallCommand(nameOrSource, options, behavior) {
     let extraPackage;
     if (nameOrSource && !configured) {
       try {
-        const entry = await packageEntryFromSource(nameOrSource, target.workspaceRoot, options);
+        const entry = await packageEntryFromSource(nameOrSource, target.workspaceRoot, { ...options, adapter: options.adapter ?? target.adapter });
         scope = entry.name;
         if (behavior.apply) {
           await writeWorkspaceConfig(target.workspaceRoot, upsertPackage(await readWorkspaceConfig(target.workspaceRoot), entry));
@@ -6407,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 });
@@ -6433,9 +6690,15 @@ function nextInstallNudge() {
   return "Preview: agentwheel plan - Apply: agentwheel install";
 }
 async function resolveCliTargets(options) {
+  if (options.all && options.allDetected) {
+    throw new Error("Choose either --all for configured agents or --all-detected for detected runtime directories.");
+  }
   if (options.all) {
     return resolveAllRuntimeTargets({ targetRoot: options.targetRoot, adapter: options.adapter, agent: options.agent, all: options.all });
   }
+  if (options.allDetected) {
+    return resolveAllDetectedRuntimeTargets({ targetRoot: options.targetRoot, adapter: options.adapter, agent: options.agent, allDetected: options.allDetected });
+  }
   return [await resolveRuntimeTarget({ targetRoot: options.targetRoot, adapter: options.adapter, agent: options.agent })];
 }
 async function resolveAdapterForTarget(target, options) {
@@ -6523,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
         };
       }),
@@ -6659,6 +6923,7 @@ function keepManifestEntryOperation(entry, targetRoot, rootId, operation, option
     graphNodeId: fresh?.graphNodeId ?? ("graphNodeId" in entry ? entry.graphNodeId : void 0),
     dependencyRole: fresh?.dependencyRole ?? ("dependencyRole" in entry ? entry.dependencyRole : "root"),
     owners: fresh?.owners ?? owners,
+    workspaceOwner: fresh?.workspaceOwner ?? ("workspaceOwner" in entry ? entry.workspaceOwner : "legacy:unowned"),
     graphLockDigest: fresh ? void 0 : "graphLockDigest" in entry ? entry.graphLockDigest : void 0
   };
 }
@@ -6702,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,
@@ -6865,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) ?? [];
@@ -6955,7 +7228,7 @@ function withFleetExample(config) {
   };
 }
 async function findAgentwheelPackageRoot(start) {
-  let current = resolve17(start);
+  let current = resolve18(start);
   while (true) {
     if (await findPackageManifestPath(current, { warnLegacy: false })) return current;
     const parent = dirname21(current);
@@ -6988,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.9.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: