agentwheel 0.8.1 → 0.10.0

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" },
@@ -542,13 +544,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 +656,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 +679,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();
@@ -1050,9 +1054,6 @@ function normalizeOwners(owners) {
 
 // src/install/apply.ts
 var execFileAsync2 = promisify2(execFile2);
-async function applyInstallPlan(plan, sourceLock, options = {}) {
-  return applyPlanTransactionally(plan, { ...options, sourceLock });
-}
 async function applyCombinedInstallPlan(plan, options = {}) {
   return applyPlanTransactionally(plan, options);
 }
@@ -1165,16 +1166,20 @@ async function applyPlanTransactionally(plan, options = {}) {
 async function uninstall(plan, options = {}) {
   const resolvedOptions = typeof options === "boolean" ? { dryRun: options } : options;
   const transport = resolvedOptions.transport ?? localTransport;
+  if (resolvedOptions.keepFiles && resolvedOptions.force) {
+    throw new Error("--keep-files cannot be combined with --force.");
+  }
   if (plan.hasBlockingChanges) {
     const blockers = plan.operations.filter((operation) => operation.action === "conflict");
     throw new Error(`Refusing to uninstall with blocking changes: ${blockers.map((item) => item.relativeDestPath).join(", ")}`);
   }
-  const removable = plan.operations.filter((operation) => operation.action === "remove" || resolvedOptions.force && operation.action === "keep").map((operation) => operation.action === "keep" ? { ...operation, action: "remove", reason: `${operation.reason}; force removing drifted managed file` } : operation);
-  const kept = resolvedOptions.force ? [] : plan.operations.filter((operation) => operation.action === "keep");
+  const removable = plan.operations.filter((operation) => operation.action === "remove" || resolvedOptions.force && isForceRemovableKeep(operation)).map((operation) => operation.action === "keep" ? { ...operation, action: "remove", reason: `${operation.reason}; force removing drifted managed file` } : operation);
+  const kept = plan.operations.filter((operation) => operation.action === "keep" && (!resolvedOptions.force || !isForceRemovableKeep(operation)));
   const skipped = plan.operations.filter((operation) => operation.action === "skip");
-  const removedDrifted = resolvedOptions.force ? plan.operations.filter((operation) => operation.action === "keep").length : 0;
-  if (resolvedOptions.dryRun) return { removed: removable.length, kept: kept.length, removedDrifted };
-  const preserved = [...kept, ...skipped];
+  const removedDrifted = resolvedOptions.force ? plan.operations.filter((operation) => operation.action === "keep" && isForceRemovableKeep(operation)).length : 0;
+  if (resolvedOptions.dryRun) return { removed: resolvedOptions.keepFiles ? 0 : removable.length, kept: kept.length, removedDrifted };
+  const preservedKept = resolvedOptions.keepFiles ? kept.filter((operation) => shouldPreserveKeptOperationWhenKeepingFiles(operation)) : kept;
+  const preserved = [...preservedKept, ...skipped];
   for (const operation of [...removable, ...preserved]) assertOperationContained(operation, plan.targetRoot);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const finalManifest = withManifestRevision({
@@ -1209,7 +1214,7 @@ async function uninstall(plan, options = {}) {
       graphLockDigest: plan.graphLockDigest,
       createdAt: now,
       updatedAt: now,
-      operations: removable,
+      operations: resolvedOptions.keepFiles ? [] : removable,
       completed: [],
       manifest: finalManifest,
       graphLockPath: resolvedOptions.graphLock?.path,
@@ -1219,7 +1224,7 @@ async function uninstall(plan, options = {}) {
       workspaceConfig: resolvedOptions.workspaceConfig?.data
     };
     await writeApplyJournal(journal, transport);
-    for (const [index, operation] of removable.entries()) {
+    for (const [index, operation] of (resolvedOptions.keepFiles ? [] : removable).entries()) {
       const backup = await recordBackup(operation, index, plan.targetRoot, plan.adapter, transport);
       journal.completed.push(backup);
       await writeApplyJournal(journal, transport);
@@ -1231,7 +1236,13 @@ async function uninstall(plan, options = {}) {
   } finally {
     await lock.release();
   }
-  return { removed: removable.length, kept: kept.length, removedDrifted };
+  return { removed: resolvedOptions.keepFiles ? 0 : removable.length, kept: kept.length, removedDrifted };
+}
+function shouldPreserveKeptOperationWhenKeepingFiles(operation) {
+  return operation.preserveInManifest === true;
+}
+function isForceRemovableKeep(operation) {
+  return operation.action === "keep" && operation.preserveInManifest !== true;
 }
 async function commitJournalState(journal, transport, entries, now) {
   const manifest = withManifestRevision({
@@ -1332,6 +1343,17 @@ async function applyOperation(operation, context) {
       graphLockDigest: context.graphLockDigest
     });
   }
+  if (operation.action === "keep") {
+    if (!operation.manifestHash || !operation.desiredHash) {
+      throw new Error(`Invalid keep operation missing manifest/source hash: ${operation.relativeDestPath}`);
+    }
+    return manifestEntryForOperation(operation, {
+      now,
+      hash: operation.manifestHash,
+      sourceHash: operation.desiredHash,
+      graphLockDigest: operation.graphLockDigest ?? context.graphLockDigest
+    });
+  }
   if (operation.action === "remove") {
     await transport.rm(operation.destPath);
     return void 0;
@@ -1370,6 +1392,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,
@@ -1377,7 +1400,7 @@ function manifestEntryForOperation(operation, values) {
     channel: operation.channel,
     packageName: operation.packageName,
     semanticCommand: operation.semanticCommand,
-    executed: values.executed,
+    executed: values.executed ?? operation.execute,
     mergeStrategy: operation.mergeStrategy,
     composedFrom: operation.composedFrom,
     graphLockDigest: operation.graphLockDigest ?? values.graphLockDigest
@@ -1441,22 +1464,6 @@ function openClawPluginInstallCommand(request) {
 }
 
 // src/install/plan.ts
-async function createInstallPlan(bundle, adapter, targetRoot, manifest, transport = localTransport) {
-  const desired = [];
-  for (const artifact of bundle.artifacts) {
-    const op = operationForArtifact(artifact, adapter, targetRoot, {
-      logicalSelector: `${artifact.type}/${artifact.name}`,
-      dependencyRole: "root",
-      owners: [artifact.packageName ?? bundle.source.packageName ?? bundle.source.source],
-      composedFrom: artifact.composedFrom
-    });
-    if (op) {
-      desired.push(op);
-    }
-  }
-  await addProgrammaticOperations(desired, adapter, targetRoot);
-  return createPlanFromOperations(desired, adapter, targetRoot, manifest, transport, {});
-}
 async function createCombinedInstallPlan(desiredArtifacts, adapter, targetRoot, manifest, transport = localTransport, options = {}) {
   for (const artifact of desiredArtifacts) {
     if (artifact.meta.dependencyRole !== "root" && isGuardedMergeTarget(artifact.type)) {
@@ -1474,6 +1481,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;
@@ -1516,6 +1527,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" });
@@ -1557,6 +1574,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",
@@ -1712,6 +1733,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` : "";
@@ -1735,6 +1766,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
   };
@@ -1757,6 +1789,7 @@ function operationMetadataFromEntry(entry) {
       graphNodeId: entry.graphNodeId,
       dependencyRole: entry.dependencyRole,
       owners: entry.owners,
+      workspaceOwner: entry.workspaceOwner,
       graphLockDigest: entry.graphLockDigest
     };
   }
@@ -1764,7 +1797,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) {
@@ -1938,7 +1995,8 @@ async function createOwnershipUninstallPlan(manifest, remainingDesired, adapter,
         mergeStrategy: entry.mergeStrategy,
         composedFrom: entry.composedFrom,
         ...operationMetadataFromEntry2(entry, remainingOwners),
-        graphLockDigest: options.graphLockDigest
+        graphLockDigest: options.graphLockDigest,
+        preserveInManifest: true
       });
       continue;
     }
@@ -2038,7 +2096,7 @@ function formatPlan(plan) {
     const dropped = plan.migrationReport.dropped.length > 0 ? `; dropped unmanaged ${plan.migrationReport.dropped.join(", ")}` : "";
     lines.push(`MIGRATE  adopted ${plan.migrationReport.adopted} legacy entries${dropped}`);
   }
-  for (const operation of plan.operations) {
+  for (const operation of sortedPlanOperations(plan.operations)) {
     const source = operation.sourcePath ? `${operation.sourcePath} -> ` : "";
     const command = operation.semanticCommand ? ` :: ${operation.semanticCommand.join(" ")}` : "";
     const blocked = operation.blockedReason ? `; ${operation.blockedReason}` : "";
@@ -2050,6 +2108,14 @@ function formatPlan(plan) {
   );
   return lines.join("\n");
 }
+function sortedPlanOperations(operations) {
+  return [...operations].sort((a, b) => {
+    const destructiveA = a.action === "remove" || a.action === "drift" || a.action === "conflict";
+    const destructiveB = b.action === "remove" || b.action === "drift" || b.action === "conflict";
+    if (destructiveA !== destructiveB) return destructiveA ? -1 : 1;
+    return a.relativeDestPath.localeCompare(b.relativeDestPath);
+  });
+}
 function formatGraphPlan(result) {
   const lines = [
     ...formatDependencyTree(result.graph),
@@ -2252,7 +2318,17 @@ var packageManifestV2Schema = z5.object({
   runtimes: runtimeListSchema.optional(),
   requires: z5.record(z5.string().min(1), packageDependencySchema).optional(),
   compose: z5.array(packageComposeEntrySchema).optional(),
-  provides: z5.array(packageProvideSchema).min(1)
+  provides: z5.array(packageProvideSchema).default([])
+}).superRefine((manifest, ctx) => {
+  const hasProvides = manifest.provides.length > 0;
+  const hasRequires = Object.keys(manifest.requires ?? {}).length > 0;
+  if (!hasProvides && !hasRequires) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      path: ["provides"],
+      message: "OpenPack v2 manifest must declare at least one provides entry or one requires dependency"
+    });
+  }
 });
 var packageManifestSchema = z5.union([packageManifestV1Schema, packageManifestV2Schema]);
 var openPackManifestNames = ["openpack.json", "openpack.jsonc"];
@@ -2693,7 +2769,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 {
@@ -4239,6 +4315,7 @@ async function resolveDependencyGraph(roots, options) {
       requiredBy: `workspace:${rootId}`,
       rootId,
       aliases: root.aliases,
+      useLock: root.useLock ?? options.lockedResolution,
       depth: 0,
       optional: false,
       chain: [`workspace:${rootId}`]
@@ -4295,19 +4372,41 @@ function createGraphLock(graph, artifacts = [], targetFingerprint, includeEdges
 }
 async function processRequirement(requirement, options, fetchCache, nodesByKey, rootResults, edgeMap) {
   try {
-    const normalized = await normalizeDependencySource(requirement.source, {
+    const lockLabel = options.offline ? "Offline" : options.frozenLock ? "Frozen lock" : "Locked install";
+    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
     });
-    const lockLabel = options.offline ? "Offline" : "Frozen lock";
-    const frozen = options.frozenLock ? lockedNodeForSource(normalized.normalizedSource, options.previousLock, lockLabel) : void 0;
+    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 {
       fetched = await fetchPackage(normalized, requirement.mode, options, fetchCache, frozen?.requestedRef);
     } catch (error) {
-      if (!options.frozenLock) throw error;
+      const usingLockedNode = frozen?.node !== void 0;
+      if (!options.frozenLock && !options.offline && !usingLockedNode) throw error;
       const message = error instanceof Error ? error.message : String(error);
       const label = frozen?.node ? `${frozen.node.id} (${normalized.normalizedSource})` : normalized.normalizedSource;
       throw new Error(`${lockLabel} cache missing or stale for locked graph node:
@@ -4407,7 +4506,7 @@ async function collectDependencyNeeds(state, fetched, options, chain) {
       if (!dependency.select?.length && !(state.fullPackageSelected && dependency.select === void 0)) continue;
       state.processedPackageAliases.add(alias);
       if (!dependencyTargetsRuntime(dependency.runtimes, options.runtime, state.node.id, alias, options.warn)) continue;
-      requirements.push(dependencyRequirement(state, fetched, alias, dependency, dependency.select, chain));
+      requirements.push(dependencyRequirement(state, fetched, alias, dependency, dependency.select, chain, options.lockedResolution === true));
     }
   }
   const artifactsBySelector = new Map(fetched.artifacts.map((artifact) => [artifactSelectorKey(artifact), artifact]));
@@ -4437,6 +4536,7 @@ async function collectDependencyNeeds(state, fetched, options, chain) {
             dependency,
             sortedUnique3([...dependency.select ?? [], parsed.selector]),
             chain,
+            options.lockedResolution === true,
             parsed.optional || dependency.optional === true,
             `required by ${parentSelector}`
           ));
@@ -4466,6 +4566,7 @@ async function collectDependencyNeeds(state, fetched, options, chain) {
           dependency,
           sortedUnique3([...dependency.select ?? [], include.selector]),
           chain,
+          options.lockedResolution === true,
           include.optional || dependency.optional === true
         ));
       }
@@ -4475,12 +4576,13 @@ async function collectDependencyNeeds(state, fetched, options, chain) {
   refreshNode(state);
   return requirements;
 }
-function dependencyRequirement(state, fetched, alias, dependency, select, chain, optional = dependency.optional ?? false, selectionReason) {
+function dependencyRequirement(state, fetched, alias, dependency, select, chain, lockByDefault, optional = dependency.optional ?? false, selectionReason) {
   return {
     source: dependency.source,
     select,
     mode: dependency.mode ?? "pinned",
     ref: dependency.ref,
+    useLock: lockByDefault || dependency.mode !== "tracking",
     declaringPackageRoot: fetched.resolved.resolvedPath,
     requiredBy: state.node.id,
     alias,
@@ -4626,7 +4728,8 @@ function dependencyTargetsRuntime(runtimes, runtime, nodeId, alias, warn) {
   return false;
 }
 async function fetchPackage(normalized, mode, options, fetchCache, refOverride) {
-  const key = `${normalized.driver}\0${normalized.normalizedSource}\0${mode}\0${refOverride ?? ""}\0${options.frozenLock ? "frozen" : ""}`;
+  const hardLockedCheckout = options.frozenLock === true || options.offline === true;
+  const key = `${normalized.driver}\0${normalized.normalizedSource}\0${mode}\0${refOverride ?? ""}\0${hardLockedCheckout ? "hard-locked" : "mutable"}`;
   const existing = fetchCache.get(key);
   if (existing) return existing;
   const promise = (async () => {
@@ -4635,7 +4738,7 @@ async function fetchPackage(normalized, mode, options, fetchCache, refOverride)
       cacheRoot: options.cacheRoot ?? join18(options.workspaceRoot, ".agentwheel", "cache"),
       mode,
       ref: refOverride ?? normalized.requestedRef,
-      frozenLock: options.frozenLock
+      frozenLock: hardLockedCheckout
     });
     const fetched = await withCachePathLock(resolved.resolvedPath, () => driver.fetch(resolved));
     const translated = await driver.translate(fetched);
@@ -4664,15 +4767,20 @@ async function fetchPackage(normalized, mode, options, fetchCache, refOverride)
   fetchCache.set(key, promise);
   return promise;
 }
-function lockedNodeForSource(normalizedSource, lock, label) {
-  if (!lock) {
-    throw new Error(`${label} requires an existing graph lock before resolving ${normalizedSource}.`);
+function lockedNodeForRequirement(normalizedSource, requirement, options, label) {
+  const hard = options.frozenLock === true || options.offline === true;
+  if (!hard && !requirement.useLock) return void 0;
+  if (!options.previousLock) {
+    if (hard) throw new Error(`${label} requires an existing graph lock before resolving ${normalizedSource}.`);
+    return void 0;
   }
-  const matches = lock.canonical.nodes.filter((node2) => node2.normalizedSource === normalizedSource);
+  const matches = options.previousLock.canonical.nodes.filter((node2) => node2.normalizedSource === normalizedSource);
   if (matches.length === 0) {
-    throw new Error(`${label} cannot resolve new source: ${normalizedSource}. Run without ${label === "Offline" ? "--offline" : "--frozen-lock"} first.`);
+    if (hard) throw new Error(`${label} cannot resolve new source: ${normalizedSource}. Run without ${label === "Offline" ? "--offline" : "--frozen-lock"} first.`);
+    return void 0;
   }
   if (matches.length > 1) {
+    if (!hard) return void 0;
     throw new Error(`${label} has multiple nodes for ${normalizedSource}; cannot choose a cached source deterministically.`);
   }
   const node = matches[0];
@@ -4681,6 +4789,59 @@ function lockedNodeForSource(normalizedSource, lock, label) {
     requestedRef: node.driver === "git" ? node.resolvedCommit ?? node.requestedRef : node.requestedRef
   };
 }
+function lockedNodeForRequirementReference(requirement, options, label) {
+  const hard = options.frozenLock === true || options.offline === true;
+  if (!hard && !requirement.useLock) return void 0;
+  if (!options.previousLock) {
+    if (hard) throw new Error(`${label} requires an existing graph lock before resolving ${requirement.source}.`);
+    return void 0;
+  }
+  let nodeId;
+  let description;
+  if (requirement.depth === 0 && requirement.rootId) {
+    const root = options.previousLock.canonical.roots.find((candidate) => candidate.rootId === requirement.rootId);
+    nodeId = root?.graphNodeId;
+    description = `root ${requirement.rootId}`;
+  } else if (requirement.parentId && requirement.alias) {
+    const edge = options.previousLock.canonical.edges.find((candidate) => candidate.from === requirement.parentId && candidate.alias === requirement.alias);
+    nodeId = edge?.to;
+    description = `dependency ${requirement.parentId}:${requirement.alias}`;
+  }
+  if (!nodeId) {
+    if (hard && description) {
+      throw new Error(`${label} cannot resolve new locked ${description}. Run without ${label === "Offline" ? "--offline" : "--frozen-lock"} first.`);
+    }
+    return void 0;
+  }
+  const node = options.previousLock.canonical.nodes.find((candidate) => candidate.id === nodeId);
+  if (!node) {
+    throw new Error(`${label} graph lock is missing node ${nodeId} for ${description ?? requirement.source}.`);
+  }
+  return {
+    node,
+    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,
+    normalizedSource: node.normalizedSource,
+    driver: node.driver,
+    requestedRef: node.requestedRef
+  };
+}
 function verifyIntegrity(integrity, sourceHash, label) {
   if (!integrity) return;
   const expected = integrity.replace(/^sha256[-:]/i, "");
@@ -4691,8 +4852,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;
@@ -4900,7 +5061,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) {
@@ -5381,26 +5542,6 @@ function defaultTrustStorePath() {
 }
 
 // src/lifecycle/source-plan.ts
-async function createSourcePlan(options) {
-  const workspaceRoot = options.workspaceRoot ?? options.targetRoot;
-  const lockMode = options.frozenLock === true || options.offline === true;
-  const resolvedInput = await resolvePackageSource(options.source, workspaceRoot, { offline: lockMode, warn: options.warn });
-  const resolvedSource = resolvedInput.source;
-  const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedSource));
-  const bundle = await stageSource(driver, resolvedSource, {
-    workspaceRoot,
-    adapter: options.adapter,
-    cacheRoot: join22(workspaceRoot, ".agentwheel", "cache"),
-    mode: options.mode,
-    frozenLock: lockMode,
-    select: options.select,
-    skills: options.skills
-  });
-  const transport = options.transport ?? localTransport;
-  const manifest = await readInstallManifest(options.targetRoot, options.adapter.name, transport);
-  const plan = await createInstallPlan(bundle, options.adapter, options.targetRoot, manifest, transport);
-  return { plan, bundle, resolvedSource, registryEntryName: resolvedInput.registryEntry?.name };
-}
 async function createGraphSourcePlan(options) {
   if (options.roots.length === 0) {
     throw new Error("At least one source is required for a graph plan.");
@@ -5412,14 +5553,14 @@ async function createGraphSourcePlan(options) {
     warnings.push(message);
     options.warn?.(message);
   };
-  const recoveredPendingApply = await recoverPendingApplyIfSafe(options.targetRoot, options.adapter.name, transport);
+  const recoveredPendingApply = options.readOnly === true ? false : await recoverPendingApplyIfSafe(options.targetRoot, options.adapter.name, transport);
   const workspaceConfig = await readMergedWorkspaceConfig(workspaceRoot, { globalRoot: options.globalRoot });
   const trustPolicy = {
     ...normalizeTrustPolicy(workspaceConfig.trust),
     acceptedSources: await readTrustedSources(workspaceRoot, options.trustStorePath)
   };
   const lockMode = options.frozenLock === true || options.offline === true;
-  const lockLabel = options.offline === true ? "Offline" : "Frozen lock";
+  const lockLabel = options.offline === true ? "Offline" : options.frozenLock === true ? "Frozen lock" : options.lockedResolution === true ? "Locked install" : "Fresh resolve";
   const targetFingerprint = computeTargetFingerprint(options.targetFingerprintParts ?? {
     adapter: options.adapter.name,
     targetRoot: options.targetRoot,
@@ -5434,6 +5575,7 @@ async function createGraphSourcePlan(options) {
     cacheRoot: join22(workspaceRoot, ".agentwheel", "cache"),
     registryClient,
     noDeps: options.noDeps,
+    lockedResolution: options.lockedResolution,
     frozenLock: lockMode,
     offline: options.offline,
     previousLock,
@@ -5444,7 +5586,7 @@ async function createGraphSourcePlan(options) {
   assertTrustArtifactPolicy(graph, trustPolicy);
   const trustEvaluation = evaluateTransitiveTrust(graph, previousLock, trustPolicy, options.trustPatterns ?? [], options.yes === true);
   await assertTrusted(trustEvaluation.promptSources, options);
-  const persistedTrustSources = await rememberTrustedSources(workspaceRoot, trustEvaluation.persistSources, options.trustStorePath);
+  const persistedTrustSources = options.readOnly === true ? [] : await rememberTrustedSources(workspaceRoot, trustEvaluation.persistSources, options.trustStorePath);
   for (const source of persistedTrustSources) warn(`remembered trusted transitive source: ${source}`);
   const bundle = await renderGraphForTarget(graph, {
     workspaceRoot,
@@ -5457,7 +5599,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,
@@ -5515,6 +5658,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) {
@@ -5542,6 +5688,10 @@ ${mismatches.map((item) => `- ${item}`).join("\n")}`);
 }
 async function assertTrusted(sources, options) {
   if (sources.length === 0) return;
+  if (options.readOnly === true) {
+    throw new Error(`New transitive sources require trust. Re-run with --yes or --trust <pattern>:
+${sources.map((source) => `- ${source}`).join("\n")}`);
+  }
   if (options.promptTrust) {
     if (await options.promptTrust(sources)) return;
     throw new Error(`Untrusted transitive sources:
@@ -5609,10 +5759,12 @@ async function syncProfile(options) {
         transport: target.transport.kind
       },
       noDeps: options.noDeps,
+      lockedResolution: options.lockedResolution,
       frozenLock: options.frozenLock,
       offline: options.offline,
       yes: options.yes,
       trustPatterns: options.trustPatterns ?? [],
+      readOnly: options.readOnly,
       isTTY: options.isTTY,
       warn: options.warn
     });
@@ -5682,7 +5834,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"] },
@@ -5691,9 +5843,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,
@@ -5722,7 +5874,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));
@@ -5731,8 +5883,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;
@@ -5744,11 +5917,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];
@@ -5777,6 +5946,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";
@@ -5858,9 +6032,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) {
@@ -5928,7 +6102,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;
@@ -5982,10 +6156,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)) {
@@ -6047,8 +6221,14 @@ function resolveCliVersion() {
 // src/cli/index.ts
 var CLI_VERSION = resolveCliVersion();
 var program = new Command();
-program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version(CLI_VERSION).option("--no-update-check", "disable npm version update check", false);
-program.command("init").argument("[kind]", "workspace or package", "workspace").option("--target-root <path>", "workspace root", process.cwd()).option("--fleet-example", "scaffold example agents and profiles in workspace config", false).action(async (kind, options) => {
+program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version(CLI_VERSION).showSuggestionAfterError(false).option("--no-update-check", "disable npm version update check", false).addHelpText("after", `
+
+Core flow:
+  $ agentwheel add github:org/agent-pack --adapter codex
+  $ agentwheel plan
+  $ agentwheel install
+`);
+program.command("init").description("initialize an agentwheel workspace or package").argument("[kind]", "workspace or package", "workspace").option("--target-root <path>", "workspace root", process.cwd()).option("--fleet-example", "scaffold example agents and profiles in workspace config", false).action(async (kind, options) => {
   const root = normalizeTargetRoot(options.targetRoot);
   if (kind === "package") {
     await initPackage(root);
@@ -6062,48 +6242,17 @@ program.command("init").argument("[kind]", "workspace or package", "workspace").
   const bootstrapPackage = config.bootstrapSkills === false ? void 0 : await defaultBootstrapPackage(root);
   const withBootstrap = bootstrapPackage ? upsertPackage(config, bootstrapPackage) : config;
   await writeWorkspaceConfig(root, options.fleetExample ? withFleetExample(withBootstrap) : withBootstrap);
-  console.log("Initialized .agentwheel/config.json.");
+  console.log(`Initialized ${workspaceConfigPath(root)}.`);
+  if (bootstrapPackage) console.log("Auto-added the agentwheel bootstrap skill for openclaw.");
+  console.log(nextInstallNudge());
 });
-program.command("add").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, []).action(async (source, options) => {
   const targetRoot = normalizeTargetRoot(options.targetRoot);
-  const selectedArtifacts = selectedArtifactsFromOptions(options);
-  const resolvedInput = await resolvePackageSource(source, targetRoot);
-  const resolvedSource = resolvedInput.source;
-  const driverName = options.driver ?? inferSourceDriverName(resolvedSource);
-  const driver = getSourceDriver(driverName);
-  const adapter = await resolveAdapter({
-    adapter: options.adapter,
-    adapterConfig: options.adapterConfig,
-    adapterModule: options.adapterModule,
-    allowAdapterCode: options.allowAdapterCode,
-    baseDir: targetRoot,
-    warn: (message) => console.warn(message)
-  });
-  const bundle = await stageSource(driver, resolvedSource, {
-    workspaceRoot: targetRoot,
-    adapter,
-    cacheRoot: join28(targetRoot, ".agentwheel", "cache"),
-    mode: options.mode,
-    select: selectedArtifacts
-  });
-  const name = options.name ?? resolvedInput.registryEntry?.name ?? bundle.source.packageName ?? source;
-  const entry = {
-    name,
-    source: resolvedSource,
-    driver: driverName,
-    adapter: adapter.name,
-    adapterConfig: options.adapterConfig,
-    adapterModule: options.adapterModule,
-    adapterCodeHash: adapter.programmatic?.hash,
-    mode: options.mode,
-    requestedRef: bundle.source.requestedRef,
-    select: selectedArtifacts
-  };
+  const entry = await packageEntryFromSource(source, targetRoot, options);
   await writeWorkspaceConfig(targetRoot, upsertPackage(await readWorkspaceConfig(targetRoot), entry));
-  await rm9(bundle.root, { recursive: true, force: true });
-  console.log(`Added ${name}.`);
+  console.log(`Added ${entry.name}. Preview: agentwheel plan - Apply: agentwheel install`);
 });
-program.command("list").argument("<source>", "package source").option("--driver <driver>", "source driver").option("--target-root <path>", "workspace root", process.cwd()).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("list").description("list artifacts exposed by a package source").argument("<source>", "package source").option("--driver <driver>", "source driver").option("--target-root <path>", "workspace root", process.cwd()).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) => {
   const targetRoot = normalizeTargetRoot(options.targetRoot);
   const selectedArtifacts = selectedArtifactsFromOptions(options);
   const resolvedInput = await resolvePackageSource(source, targetRoot);
@@ -6114,7 +6263,7 @@ program.command("list").argument("<source>", "package source").option("--driver
     console.log(`${artifact.type}	${artifact.name}	${artifact.relativePath}`);
   }
 });
-program.command("scan").argument("<source>", "package source").option("--driver <driver>", "source driver").option("--target-root <path>", "workspace root", process.cwd()).action(async (source, options) => {
+program.command("scan").description("scan a package source for validation findings").argument("<source>", "package source").option("--driver <driver>", "source driver").option("--target-root <path>", "workspace root", process.cwd()).action(async (source, options) => {
   const targetRoot = normalizeTargetRoot(options.targetRoot);
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
@@ -6129,99 +6278,28 @@ program.command("scan").argument("<source>", "package source").option("--driver
   }
   if (!result.ok) process.exitCode = 1;
 });
-program.command("plan").argument("[source]", "source directory").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", false).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) => {
-  const targets = await resolveCliTargets(options);
-  for (const target of targets) {
-    if (source && options.noDeps && options.onlySource) {
-      const { plan, bundle } = await buildPlan(source, target, options);
-      console.log(formatPlan(plan));
-      await rm9(bundle.root, { recursive: true, force: true });
-      if (plan.hasBlockingChanges) process.exitCode = 1;
-      continue;
-    }
-    for (const result of await buildGraphPlansForTarget(target, source, options, { useUpdateDecision: false })) {
-      console.log(formatGraphPlan(result));
-      await rm9(result.bundle.root, { recursive: true, force: true });
-      if (result.plan.hasBlockingChanges) 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) => {
+  await runInstallCommand(source, { ...options, dryRun: true }, { apply: false });
 });
-program.command("sync").argument("[source]", "source directory").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", false).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) => {
-  if (options.profile) {
-    const target = await resolveRuntimeTarget({ targetRoot: options.targetRoot, adapter: options.adapter, agent: options.agent });
-    const results = await syncProfile({
-      workspaceRoot: target.workspaceRoot,
-      profile: options.profile,
-      source,
-      driver: options.driver,
-      mode: options.mode,
-      select: selectedArtifactsFromOptions(options),
-      dryRun: options.dryRun,
-      executePlugins: options.executePlugins,
-      allowAdapterCode: options.allowAdapterCode,
-      noDeps: options.noDeps,
-      frozenLock: options.frozenLock,
-      offline: options.offline,
-      yes: options.yes,
-      trustPatterns: options.trust ?? [],
-      isTTY: process.stdin.isTTY === true,
-      warn: (message) => console.warn(message)
-    });
-    for (const result of results) {
-      console.log(`Profile ${options.profile} / ${result.runtime} / ${result.packageName} at ${result.targetRoot} (${result.transport}):`);
-      console.log(formatPlan(result.plan));
-      if (result.plan.hasBlockingChanges) process.exitCode = 1;
-    }
-    if (!options.dryRun) console.log("Applied.");
-    return;
-  }
-  const targets = await resolveCliTargets(options);
-  if (!source) {
-    for (const target of targets) {
-      await runConfiguredGraphPackages(target, options, { useUpdateDecision: false });
-    }
-    return;
-  }
-  for (const target of targets) {
-    if (options.noDeps && options.onlySource) {
-      const { plan, bundle } = await buildPlan(source, target, options);
-      console.log(formatPlan(plan));
-      if (!options.dryRun) {
-        await applyInstallPlan(plan, bundle.sourceLock, { executePlugins: options.executePlugins, transport: transportForTarget(target) });
-        console.log(`Applied ${target.adapter} at ${target.targetRoot}.`);
-      }
-      await rm9(bundle.root, { recursive: true, force: true });
-      if (plan.hasBlockingChanges) process.exitCode = 1;
-      continue;
-    }
-    for (const result of await buildGraphPlansForTarget(target, source, options, { useUpdateDecision: false })) {
-      console.log(formatGraphPlan(result));
-      if (!options.dryRun) {
-        await applyCombinedInstallPlan(result.plan, {
-          executePlugins: options.executePlugins,
-          transport: transportForTarget(target),
-          graphLockDigest: result.graphLockDigest,
-          graphLock: { path: result.graphLockPath, lock: result.bundle.graphLock }
-        });
-        console.log(`Applied ${result.plan.adapter} at ${result.plan.targetRoot}.`);
-      }
-      await rm9(result.bundle.root, { recursive: true, force: true });
-      if (result.plan.hasBlockingChanges) process.exitCode = 1;
-    }
-  }
+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) => {
+  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) => {
+  console.error("warning: 'agentwheel sync' is deprecated and will be removed in 0.10. Use 'agentwheel install'.");
+  await runInstallCommand(source, options, { apply: !options.dryRun });
 });
-program.command("update").option("--adapter <adapter>", "built-in adapter").option("--target-root <path>", "workspace root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--dry-run", "show plans without writing", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--allow-adapter-code", "allow loading local adapter code from configured packages", false).option("--select <type/name>", "temporarily select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "temporarily select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--no-deps", "resolve only root sources and ignore requires with a warning", 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 (options) => {
+program.command("update").description("re-resolve tracking packages, then apply the result").argument("[name]", "configured package name or source to update").option("--adapter <adapter>", "built-in adapter").option("--target-root <path>", "workspace root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--dry-run", "show plans without writing", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--allow-adapter-code", "allow loading local adapter code from configured packages", false).option("--select <type/name>", "temporarily select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "temporarily select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (name, options) => {
   const targets = await resolveCliTargets(options);
   for (const target of targets) {
-    await runConfiguredGraphPackages(target, options, { useUpdateDecision: true });
+    await runConfiguredGraphPackages(target, { ...options, scope: name }, { mode: "update" });
   }
 });
 program.command("deps").description("inspect the OpenPack dependency graph").addCommand(
-  new Command("tree").argument("[source]", "optional source directory to resolve").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("--no-deps", "resolve only root sources and ignore requires with a warning", 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) => {
+  new Command("tree").description("print the OpenPack dependency graph").argument("[source]", "optional package source to resolve").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("--no-deps", "resolve only root sources and ignore requires with a warning").option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (source, options) => {
     const targets = await resolveCliTargets(options);
     for (const target of targets) {
       if (source) {
-        for (const result of await buildGraphPlansForTarget(target, source, options, { useUpdateDecision: false })) {
+        for (const result of await buildGraphPlansForTarget(target, source, options, { mode: "install" })) {
           console.log(formatDependencyTree(result.graph).join("\n"));
           for (const decision of result.bundle.graphLock.canonical.namespacing) {
             console.log(`NAMESPACE ${decision.graphNodeId}:${decision.type}/${decision.name} -> ${decision.type}/${decision.installName} (${decision.reason})`);
@@ -6235,7 +6313,7 @@ program.command("deps").description("inspect the OpenPack dependency graph").add
     }
   })
 ).addCommand(
-  new Command("why").argument("<selector>", "installed path, type/installName, or graphNodeId:type/name").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).action(async (selector, options) => {
+  new Command("why").description("explain why an artifact is installed").argument("<selector>", "installed path, type/installName, or graphNodeId:type/name").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).action(async (selector, options) => {
     const targets = await resolveCliTargets(options);
     for (const target of targets) {
       const { lock, adapter } = await readTargetGraphLock(target, options);
@@ -6262,7 +6340,7 @@ program.command("registry").description("manage optional registry indexes").addC
   })
 );
 program.command("trust").description("manage persisted source trust decisions").addCommand(
-  new Command("forget").argument("<pattern>", "trusted source glob to revoke").option("--target-root <path>", "workspace root", process.cwd()).action(async (pattern, options) => {
+  new Command("forget").description("forget a persisted trusted source pattern").argument("<pattern>", "trusted source glob to revoke").option("--target-root <path>", "workspace root", process.cwd()).action(async (pattern, options) => {
     const removed = await forgetTrustedSources(normalizeTargetRoot(options.targetRoot), pattern);
     if (removed.length === 0) {
       console.log(`No persisted trust matched ${pattern}.`);
@@ -6289,23 +6367,31 @@ program.command("package").description("validate and migrate OpenPack packages")
     console.log(result.message);
   })
 );
-program.command("remember").requiredOption("--runtime <runtime>", "runtime/adapter name").option("--target-root <path>", "workspace root", process.cwd()).argument("<text>", "text to append to the local instructions overlay").action(async (text, options) => {
+program.command("remember").description("append text to the local instructions overlay").requiredOption("--runtime <runtime>", "runtime/adapter name").option("--target-root <path>", "workspace root", process.cwd()).argument("<text>", "text to append to the local instructions overlay").action(async (text, options) => {
   const targetRoot = normalizeTargetRoot(options.targetRoot);
   const result = await remember(targetRoot, options.runtime, text);
-  console.log(`Remembered in ${result.overlayPath}. Run: agentwheel sync <source> --adapter ${options.runtime}`);
+  console.log(`Remembered in ${result.overlayPath}.`);
+  console.log(nextInstallNudge());
 });
-program.command("eject").argument("<item>", "package/type/name").option("--target-root <path>", "workspace root", process.cwd()).action(async (item, options) => {
+program.command("eject").description("copy a managed artifact into local ownership").argument("<item>", "package/type/name").option("--target-root <path>", "workspace root", process.cwd()).action(async (item, options) => {
   const targetRoot = normalizeTargetRoot(options.targetRoot);
   const result = await ejectArtifact(targetRoot, item);
   console.log(`Ejected ${item} to ${result.ejectedPath}.`);
+  console.log(nextInstallNudge());
 });
-program.command("uninstall").argument("[package]", "configured package name or source to remove from the ownership graph").option("--adapter <adapter>", "adapter").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("--dry-run", "show removals without writing", false).option("--force", "remove drifted managed files too", false).option("--select <type/name>", "uninstall only selected artifact type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "uninstall only selected skill name (repeatable or comma-separated)", collectSkillOption, []).option("--frozen-lock", "resolve remaining packages strictly from the existing graph lock and cached sources", false).option("--offline", "resolve remaining packages strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources while resolving remaining packages", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (packageName, options) => {
+program.command("uninstall").description("remove configured packages or managed runtime files").argument("[package]", "configured package name or source to remove from the ownership graph").option("--adapter <adapter>", "adapter").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("--dry-run", "show removals without writing", false).option("--force", "remove drifted managed files too", false).option("--keep-files", "remove from config and manifest but leave runtime files unmanaged", false).option("--select <type/name>", "uninstall only selected artifact type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "uninstall only selected skill name (repeatable or comma-separated)", collectSkillOption, []).option("--frozen-lock", "resolve remaining packages strictly from the existing graph lock and cached sources", false).option("--offline", "resolve remaining packages strictly from graph locks and local caches", false).option("--yes", "trust all new transitive sources while resolving remaining packages", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (packageName, options) => {
+  if (options.keepFiles && options.force) {
+    throw new Error("--keep-files cannot be combined with --force.");
+  }
   const targets = await resolveCliTargets(options);
   for (const target of targets) {
     if (packageName) {
       await uninstallConfiguredPackage(target, packageName, options);
       continue;
     }
+    if (options.keepFiles) {
+      throw new Error("--keep-files requires a configured package name or source.");
+    }
     const adapter = await resolveAdapterForTarget(target, options);
     const transport = transportForTarget(target);
     const manifest = await readInstallManifest(target.targetRoot, adapter.name, transport);
@@ -6326,28 +6412,149 @@ program.command("uninstall").argument("[package]", "configured package name or s
     if (plan.hasBlockingChanges) process.exitCode = 1;
   }
 });
-async function buildPlan(source, target, options) {
-  const adapter = await resolveAdapterForTarget(target, options);
-  const transport = transportForTarget(target);
-  const result = await createSourcePlan({
-    source,
-    targetRoot: target.targetRoot,
-    workspaceRoot: target.workspaceRoot,
+program.command("status").description("show configured packages and runtime install state").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).action(async (options) => {
+  const targets = await resolveCliTargets(options);
+  for (const target of targets) {
+    await printStatus(target, options);
+  }
+});
+async function runInstallCommand(nameOrSource, options, behavior) {
+  if (options.profile) {
+    const target = await resolveRuntimeTarget({ targetRoot: options.targetRoot, adapter: options.adapter, agent: options.agent });
+    const results = await syncProfile({
+      workspaceRoot: target.workspaceRoot,
+      profile: options.profile,
+      source: nameOrSource,
+      driver: options.driver,
+      mode: options.mode,
+      select: selectedArtifactsFromOptions(options),
+      dryRun: !behavior.apply,
+      executePlugins: options.executePlugins,
+      allowAdapterCode: options.allowAdapterCode,
+      noDeps: noDepsFromOptions(options),
+      lockedResolution: true,
+      frozenLock: options.frozenLock,
+      offline: options.offline,
+      yes: options.yes,
+      trustPatterns: options.trust ?? [],
+      readOnly: !behavior.apply,
+      isTTY: process.stdin.isTTY === true,
+      warn: (message) => console.warn(message)
+    });
+    for (const result of results) {
+      console.log(`Profile ${options.profile} / ${result.runtime} / ${result.packageName} at ${result.targetRoot} (${result.transport}):`);
+      console.log(formatPlan(result.plan));
+      if (result.plan.hasBlockingChanges) process.exitCode = 1;
+    }
+    if (behavior.apply) console.log("Applied.");
+    return;
+  }
+  const targets = await resolveCliTargets(options);
+  for (const target of targets) {
+    const config = await readMergedWorkspaceConfig(target.workspaceRoot);
+    const configured = nameOrSource ? findConfiguredPackage(config.packages, nameOrSource) : void 0;
+    let source;
+    let scope = configured?.name;
+    let extraPackage;
+    if (nameOrSource && !configured) {
+      try {
+        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));
+        } else {
+          source = nameOrSource;
+          extraPackage = entry;
+        }
+      } catch (error) {
+        throw teachingInstallError(nameOrSource, error);
+      }
+    }
+    for (const result of await buildGraphPlansForTarget(target, source, { ...options, scope, extraPackage }, { mode: "install" })) {
+      console.log(formatGraphPlan(result));
+      if (behavior.apply) {
+        await applyCombinedInstallPlan(result.plan, {
+          executePlugins: options.executePlugins,
+          transport: transportForTarget(target),
+          graphLockDigest: result.graphLockDigest,
+          graphLock: { path: result.graphLockPath, lock: result.bundle.graphLock }
+        });
+        console.log(`Applied ${result.plan.adapter} at ${result.plan.targetRoot}.`);
+      }
+      await rm9(result.bundle.root, { recursive: true, force: true });
+      if (result.plan.hasBlockingChanges) process.exitCode = 1;
+    }
+  }
+}
+async function packageEntryFromSource(source, targetRoot, options) {
+  const selectedArtifacts = selectedArtifactsFromOptions(options);
+  const lockMode = options.frozenLock === true || options.offline === true;
+  const resolvedInput = await resolvePackageSource(source, targetRoot, { offline: lockMode });
+  const resolvedSource = resolvedInput.source;
+  const driverName = options.driver ?? inferSourceDriverName(resolvedSource);
+  const driver = getSourceDriver(driverName);
+  const adapter = await resolveAdapter({
+    adapter: options.adapter ?? "openclaw",
+    adapterConfig: options.adapterConfig,
+    adapterModule: options.adapterModule,
+    allowAdapterCode: options.allowAdapterCode,
+    baseDir: targetRoot,
+    warn: (message) => console.warn(message)
+  });
+  const bundle = await stageSource(driver, resolvedSource, {
+    workspaceRoot: targetRoot,
     adapter,
-    driver: options.driver,
+    cacheRoot: join28(targetRoot, ".agentwheel", "cache"),
     mode: options.mode,
-    select: selectedArtifactsFromOptions(options),
-    frozenLock: options.frozenLock,
-    offline: options.offline,
-    warn: (message) => console.warn(message),
-    transport
+    frozenLock: lockMode,
+    select: selectedArtifacts
   });
-  return { plan: result.plan, bundle: result.bundle };
+  try {
+    return {
+      name: options.name ?? resolvedInput.registryEntry?.name ?? bundle.source.packageName ?? source,
+      source: resolvedSource,
+      driver: driverName,
+      adapter: adapter.name,
+      adapterConfig: options.adapterConfig,
+      adapterModule: options.adapterModule,
+      adapterCodeHash: adapter.programmatic?.hash,
+      mode: options.mode ?? "pinned",
+      requestedRef: bundle.source.requestedRef,
+      select: selectedArtifacts
+    };
+  } finally {
+    await rm9(bundle.root, { recursive: true, force: true });
+  }
+}
+function findConfiguredPackage(packages, value) {
+  return packages.find((pkg) => pkg.name === value || pkg.source === value);
+}
+function noDepsFromOptions(options) {
+  return options.noDeps === true || options.deps === false;
+}
+function teachingInstallError(input, cause) {
+  const message = cause instanceof Error ? cause.message : String(cause);
+  return new Error(
+    `'${input}' is not a configured package and could not be resolved as a source.
+  To add and install a new package:   agentwheel install <source>   (e.g. github:org/pack)
+  To see what's configured:   agentwheel status
+
+Resolver error: ${message}`
+  );
+}
+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) {
@@ -6363,7 +6570,7 @@ async function resolveAdapterForTarget(target, options) {
 async function runConfiguredGraphPackages(target, options, behavior) {
   const results = await buildGraphPlansForTarget(target, void 0, options, behavior);
   for (const result of results) {
-    console.log(`${behavior.useUpdateDecision ? "Update" : "Sync"} ${result.plan.adapter} at ${result.plan.targetRoot}:`);
+    console.log(`${behavior.mode === "update" ? "Update" : "Install"} ${result.plan.adapter} at ${result.plan.targetRoot}:`);
     console.log(formatGraphPlan(result));
     if (!options.dryRun) {
       await applyCombinedInstallPlan(result.plan, {
@@ -6378,10 +6585,13 @@ async function runConfiguredGraphPackages(target, options, behavior) {
     if (result.plan.hasBlockingChanges) process.exitCode = 1;
   }
 }
-async function buildGraphPlansForTarget(target, source, options, _behavior) {
+async function buildGraphPlansForTarget(target, source, options, behavior) {
   const config = await readMergedWorkspaceConfig(target.workspaceRoot);
   const groups = /* @__PURE__ */ new Map();
   const selectedArtifacts = selectedArtifactsFromOptions(options);
+  const scopedPackage = options.scope ? findConfiguredPackage(config.packages, options.scope) : void 0;
+  const scopedRootId = scopedPackage?.name ?? (source ? options.scope : void 0);
+  if (options.scope && !scopedPackage && !source) throw new Error(`Configured package not found: ${options.scope}`);
   if (!source || !options.onlySource) {
     for (const pkg of config.packages) {
       const group = graphGroupForPackage(groups, target, pkg, options);
@@ -6403,14 +6613,11 @@ async function buildGraphPlansForTarget(target, source, options, _behavior) {
         allowAdapterCode: options.allowAdapterCode
       },
       packages: [],
-      extraRoots: []
+      extraRoots: [],
+      extraPackages: []
     };
-    group.extraRoots.push({
-      rootId: `source:${source}`,
-      source,
-      mode: options.mode ?? "pinned",
-      select: selectedArtifacts
-    });
+    const entry = options.extraPackage ?? await packageEntryFromSource(source, target.workspaceRoot, options);
+    group.extraPackages.push(entry);
     groups.set(key, group);
   }
   if (groups.size === 0) {
@@ -6420,36 +6627,161 @@ async function buildGraphPlansForTarget(target, source, options, _behavior) {
   const results = [];
   for (const group of groups.values()) {
     const adapter = await resolveAdapterForTarget(group.target, group.adapterOptions);
+    const transport = transportForTarget(group.target);
+    const allPackages = [...group.packages, ...group.extraPackages];
+    const groupHasScope = !scopedRootId || allPackages.some((pkg) => pkg.name === scopedRootId || pkg.source === options.scope);
+    if (behavior.mode === "install" && scopedRootId && !groupHasScope) continue;
+    const updateScope = behavior.mode === "update" ? scopedPackage ? /* @__PURE__ */ new Set([scopedPackage.name]) : void 0 : void 0;
     const roots = [
-      ...group.packages.map((pkg) => ({
-        rootId: pkg.name,
-        source: pkg.source,
-        mode: pkg.mode,
-        ref: pkg.requestedRef,
-        select: selectedArtifacts ?? normalizeArtifactSelectors(pkg.select, pkg.skills),
-        aliases: pkg.aliases
-      })),
+      ...allPackages.map((pkg) => {
+        const updateThisPackage = behavior.mode === "update" && pkg.mode === "tracking" && (!updateScope || updateScope.has(pkg.name) || updateScope.has(pkg.source));
+        return {
+          rootId: pkg.name,
+          source: pkg.source,
+          mode: pkg.mode,
+          ref: pkg.requestedRef,
+          select: selectedArtifacts ?? normalizeArtifactSelectors(pkg.select, pkg.skills),
+          aliases: pkg.aliases,
+          useLock: behavior.mode === "install" ? true : !updateThisPackage
+        };
+      }),
       ...group.extraRoots
     ];
+    if (behavior.mode === "update") {
+      const changed = roots.filter((root) => root.useLock === false);
+      if (changed.length === 0) {
+        const label = options.scope ? ` ${options.scope}` : "";
+        console.log(`No tracking packages to update${label}.`);
+        continue;
+      }
+    }
     if (roots.length === 0) continue;
-    results.push(await createGraphSourcePlan({
+    const result = await createGraphSourcePlan({
       roots,
       targetRoot: group.target.targetRoot,
       workspaceRoot: group.target.workspaceRoot,
       adapter,
-      transport: transportForTarget(group.target),
+      transport,
       targetKey: group.target.agentName ?? group.target.source,
       targetFingerprintParts: targetFingerprintParts(group.target, adapter, group.adapterOptions),
-      noDeps: options.noDeps,
+      noDeps: noDepsFromOptions(options),
+      lockedResolution: behavior.mode === "install",
       frozenLock: options.frozenLock,
       offline: options.offline,
       yes: options.yes,
       trustPatterns: options.trust ?? [],
+      readOnly: options.dryRun === true,
       isTTY: process.stdin.isTTY === true
-    }));
+    });
+    if (behavior.mode === "install" && scopedRootId) {
+      const manifest = await readInstallManifest(group.target.targetRoot, adapter.name, transport);
+      results.push(scopeInstallPlanToRoot(result, scopedRootId, manifest));
+    } else {
+      results.push(result);
+    }
   }
   return results;
 }
+function scopeInstallPlanToRoot(result, rootId, manifest) {
+  const scopedOwners = scopedGraphOwnerKeys(result, rootId);
+  const manifestByPath = new Map((manifest?.entries ?? []).map((entry) => [entry.path, entry]));
+  const preservedPaths = /* @__PURE__ */ new Set();
+  const plannedPaths = /* @__PURE__ */ new Set();
+  const operations = [];
+  for (const operation of result.plan.operations) {
+    plannedPaths.add(operation.relativeDestPath);
+    if (operationBelongsToScopedRoot(operation, scopedOwners)) {
+      operations.push(operation);
+      continue;
+    }
+    const entry = manifestByPath.get(operation.relativeDestPath);
+    const transformed = transformOutOfScopeOperation(operation, entry, result.plan.targetRoot, rootId);
+    for (const scopedOperation of transformed) {
+      if (preservedPaths.has(scopedOperation.relativeDestPath)) continue;
+      preservedPaths.add(scopedOperation.relativeDestPath);
+      operations.push(scopedOperation);
+    }
+  }
+  for (const entry of manifest?.entries ?? []) {
+    if (plannedPaths.has(entry.path) || preservedPaths.has(entry.path) || entryBelongsToScopedRoot(entry, scopedOwners)) continue;
+    preservedPaths.add(entry.path);
+    operations.push(keepManifestEntryOperation(entry, result.plan.targetRoot, rootId));
+  }
+  return {
+    ...result,
+    plan: {
+      ...result.plan,
+      operations,
+      hasBlockingChanges: operations.some((operation) => operation.action === "drift" || operation.action === "conflict")
+    }
+  };
+}
+function transformOutOfScopeOperation(operation, entry, targetRoot, rootId) {
+  if (operation.action === "skip") return [operation];
+  if (operation.action === "update" || operation.action === "drift") {
+    return entry ? [keepManifestEntryOperation(entry, targetRoot, rootId, operation, { freshMetadata: true })] : [];
+  }
+  if (operation.action === "remove") {
+    return entry ? [keepManifestEntryOperation(entry, targetRoot, rootId)] : [];
+  }
+  if (operation.action === "plugin" || operation.action === "program") {
+    return entry ? [keepManifestEntryOperation(entry, targetRoot, rootId)] : [];
+  }
+  return [];
+}
+function scopedGraphOwnerKeys(result, rootId) {
+  const root = result.graph.roots.find((candidate) => candidate.rootId === rootId);
+  if (!root) throw new Error(`Resolved graph root not found for scoped install: ${rootId}`);
+  const keys = /* @__PURE__ */ new Set([`workspace:${rootId}`]);
+  const queue = [root.graphNodeId];
+  while (queue.length > 0) {
+    const nodeId = queue.shift();
+    if (keys.has(nodeId)) continue;
+    keys.add(nodeId);
+    for (const edge of result.graph.edges) {
+      if (edge.from === nodeId) queue.push(edge.to);
+    }
+  }
+  return keys;
+}
+function operationBelongsToScopedRoot(operation, scopedOwners) {
+  if (operation.graphNodeId && scopedOwners.has(operation.graphNodeId)) return true;
+  return operation.owners?.some((owner) => scopedOwners.has(owner)) === true;
+}
+function entryBelongsToScopedRoot(entry, scopedOwners) {
+  if ("graphNodeId" in entry && entry.graphNodeId && scopedOwners.has(entry.graphNodeId)) return true;
+  const owners = "owners" in entry ? entry.owners : [entry.packageName ?? "legacy"];
+  return owners.some((owner) => scopedOwners.has(owner));
+}
+function keepManifestEntryOperation(entry, targetRoot, rootId, operation, options = {}) {
+  const owners = "owners" in entry ? entry.owners : [entry.packageName ?? "legacy"];
+  const fresh = options.freshMetadata ? operation : void 0;
+  return {
+    action: "keep",
+    artifactType: entry.artifactType,
+    artifactName: entry.artifactName,
+    kind: entry.kind,
+    destPath: operation?.destPath ?? join28(targetRoot, entry.path),
+    relativeDestPath: entry.path,
+    desiredHash: entry.sourceHash,
+    currentHash: operation?.currentHash ?? entry.hash,
+    manifestHash: entry.hash,
+    reason: `preserved outside scoped install ${rootId}`,
+    channel: entry.channel,
+    packageName: entry.packageName,
+    semanticCommand: entry.semanticCommand,
+    execute: entry.executed,
+    mergeStrategy: entry.mergeStrategy,
+    composedFrom: entry.composedFrom,
+    installName: fresh?.installName ?? ("installName" in entry ? entry.installName : entry.artifactName),
+    logicalSelector: fresh?.logicalSelector ?? ("logicalSelector" in entry ? entry.logicalSelector : `${entry.artifactType}/${entry.artifactName}`),
+    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
+  };
+}
 async function uninstallConfiguredPackage(target, packageName, options) {
   const config = await readMergedWorkspaceConfig(target.workspaceRoot);
   const removed = config.packages.filter((pkg) => pkg.name === packageName || pkg.source === packageName);
@@ -6498,10 +6830,12 @@ async function uninstallConfiguredPackage(target, packageName, options) {
         transport,
         targetKey: remainingGroup.target.agentName ?? remainingGroup.target.source,
         targetFingerprintParts: targetFingerprintParts(remainingGroup.target, remainingAdapter, remainingGroup.adapterOptions),
+        lockedResolution: true,
         frozenLock: options.frozenLock,
         offline: options.offline,
         yes: options.yes,
         trustPatterns: options.trust ?? [],
+        readOnly: options.dryRun === true,
         isTTY: process.stdin.isTTY === true
       });
       remainingGraphPlan = result2;
@@ -6522,6 +6856,7 @@ async function uninstallConfiguredPackage(target, packageName, options) {
     const result = await uninstall(plan, {
       dryRun: options.dryRun,
       force: options.force,
+      keepFiles: options.keepFiles,
       transport,
       ...graphLockFinalState,
       workspaceConfig: {
@@ -6550,7 +6885,8 @@ function graphGroupForPackage(groups, target, pkg, options) {
     target: packageTarget,
     adapterOptions,
     packages: [],
-    extraRoots: []
+    extraRoots: [],
+    extraPackages: []
   };
   groups.set(key, created);
   return created;
@@ -6593,6 +6929,53 @@ async function readTargetGraphLock(target, options) {
   }
   return { adapter, path, lock: await readGraphLock(path) };
 }
+async function printStatus(target, options) {
+  const config = await readMergedWorkspaceConfig(target.workspaceRoot);
+  const adapter = await resolveAdapterForTarget(target, options);
+  const transport = transportForTarget(target);
+  console.log(`Status for ${adapter.name} at ${target.targetRoot}`);
+  if (config.packages.length === 0) {
+    console.log(`Configured packages: none at ${target.workspaceRoot}`);
+    return;
+  }
+  console.log("Configured packages:");
+  for (const pkg of config.packages) {
+    console.log(`- ${pkg.name} (${pkg.mode}) ${pkg.source}`);
+  }
+  const manifest = await readInstallManifest(target.targetRoot, adapter.name, transport);
+  console.log(manifest ? `Install manifest: ${manifest.entries.length} entries, revision ${manifest.revision}` : "Install manifest: missing");
+  try {
+    const { path, lock } = await readTargetGraphLock(target, options);
+    console.log(`Graph lock: ${path}`);
+    console.log(`Locked graph: ${lock.canonical.roots.length} roots, ${lock.canonical.nodes.length} nodes, ${lock.canonical.artifacts.length} artifacts`);
+  } catch {
+    console.log("Graph lock: missing");
+  }
+  await printPendingInstallWork(target, options);
+}
+async function printPendingInstallWork(target, options) {
+  let results = [];
+  try {
+    results = await buildGraphPlansForTarget(target, void 0, { ...options, dryRun: true }, { mode: "install" });
+    const operations = results.flatMap((result) => result.plan.operations);
+    const pending = operations.filter((operation) => operation.action !== "skip");
+    if (pending.length === 0) {
+      console.log("Pending install work: none");
+      return;
+    }
+    const counts = [...pending.reduce((map, operation) => {
+      map.set(operation.action, (map.get(operation.action) ?? 0) + 1);
+      return map;
+    }, /* @__PURE__ */ new Map())].map(([action, count]) => `${action}=${count}`).join(", ");
+    const blocking = pending.filter((operation) => operation.action === "conflict" || operation.action === "drift").length;
+    console.log(`Pending install work: ${pending.length} operations (${counts}${blocking ? `; blocking=${blocking}` : ""})`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.log(`Pending install work: unavailable (${message})`);
+  } finally {
+    await Promise.all(results.map((result) => rm9(result.bundle.root, { recursive: true, force: true })));
+  }
+}
 function collectSelectOption(value, previous) {
   return [...previous, ...splitSelectorList(value)];
 }
@@ -6692,7 +7075,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);