@yansirplus/cli 0.5.18 → 0.5.20

package/dist/consumer-overlay.mjs

@@ -4,6 +4,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { workspacePackagePaths } from "./lib/workspace-manifest.mjs";
+
 export const installManifestProtocol = "agentos-install-manifest@1";
 export const localConsumerMarkerName = ".agentos-local.json";
 
@@ -112,6 +114,57 @@ export const consumerManifestFiles = (consumerRoot) =>
     (name) => path.join(consumerRoot, name),
   );
 
+const packageNameForRoot = (consumerRoot) => {
+  const file = path.join(consumerRoot, "package.json");
+  if (!fs.existsSync(file)) return undefined;
+  const name = readJson(file).name;
+  return typeof name === "string" && name.length > 0 ? name : undefined;
+};
+
+const consumerWorkspaceLayout = (consumerRoot) => {
+  const manifest = path.join(consumerRoot, "pnpm-workspace.yaml");
+  const root = {
+    kind: "root",
+    relativePath: ".",
+    consumerRoot,
+    packageName: packageNameForRoot(consumerRoot),
+  };
+  if (!fs.existsSync(manifest)) {
+    return { status: "not_workspace", roots: [root] };
+  }
+  try {
+    const roots = [
+      root,
+      ...workspacePackagePaths(consumerRoot).map((relativePath) => {
+        const packageRoot = path.join(consumerRoot, relativePath);
+        return {
+          kind: "workspace-package",
+          relativePath,
+          consumerRoot: packageRoot,
+          packageName: packageNameForRoot(packageRoot),
+        };
+      }),
+    ];
+    return {
+      status: "workspace",
+      manifestPath: path.relative(consumerRoot, manifest).split(path.sep).join("/"),
+      roots,
+    };
+  } catch (error) {
+    return {
+      status: "invalid",
+      manifestPath: path.relative(consumerRoot, manifest).split(path.sep).join("/"),
+      error: error instanceof Error ? error.message : String(error),
+      roots: [root],
+    };
+  }
+};
+
+const consumerWorkspaceManifestFiles = (layout) =>
+  [...new Set(layout.roots.flatMap((root) => consumerManifestFiles(root.consumerRoot)))].sort(
+    (left, right) => left.localeCompare(right),
+  );
+
 export const snapshotFiles = (files) =>
   new Map(files.map((file) => [file, fs.existsSync(file) ? fs.readFileSync(file) : undefined]));
 
@@ -289,6 +342,9 @@ const fileSpecPath = (spec) => {
   return spec.slice("file:".length);
 };
 
+const optionalFileSpecPath = (spec) =>
+  typeof spec === "string" && spec.startsWith("file:") ? spec.slice("file:".length) : undefined;
+
 export const tarballPackageEntries = (manifest) =>
   Object.entries(manifest.tarballs)
     .map(([packageName, entry]) => {
@@ -321,6 +377,326 @@ const markerArtifact = (manifestPath, manifest) => ({
   },
 });
 
+const sourcePackageScope = "@agent-os";
+
+const releaseNpmScope = (sourceRoot) => {
+  if (typeof sourceRoot !== "string") return undefined;
+  const manifestPath = path.join(sourceRoot, "package.json");
+  if (!fs.existsSync(manifestPath)) return undefined;
+  const manifest = readJson(manifestPath);
+  return typeof manifest.agentOsRelease?.npmScope === "string"
+    ? manifest.agentOsRelease.npmScope
+    : undefined;
+};
+
+const publicPackageName = (sourceName, npmScope) => {
+  if (typeof npmScope !== "string" || !sourceName.startsWith(`${sourcePackageScope}/`)) {
+    return sourceName;
+  }
+  return `${npmScope}/${sourceName.slice(sourcePackageScope.length + 1)}`;
+};
+
+const sourceManifestPathForPackage = (packageName, sourceRoot) => {
+  if (typeof sourceRoot !== "string") return undefined;
+  const surfacePath = path.join(sourceRoot, "docs", "surface.json");
+  if (!fs.existsSync(surfacePath)) return undefined;
+  const npmScope = releaseNpmScope(sourceRoot);
+  const surface = readJson(surfacePath);
+  for (const pkg of surface.packages ?? []) {
+    if (pkg?.published !== true || typeof pkg.name !== "string" || typeof pkg.path !== "string") {
+      continue;
+    }
+    if (packageName !== pkg.name && packageName !== publicPackageName(pkg.name, npmScope)) {
+      continue;
+    }
+    const manifestPath = path.join(sourceRoot, pkg.path, "package.json");
+    return fs.existsSync(manifestPath) ? manifestPath : undefined;
+  }
+  return undefined;
+};
+
+const collectExportTargetStrings = (value, output = []) => {
+  if (typeof value === "string") {
+    output.push(value);
+    return output;
+  }
+  if (value === null || typeof value !== "object") return output;
+  for (const child of Object.values(value)) collectExportTargetStrings(child, output);
+  return output;
+};
+
+const exportTargetKind = (target) => {
+  if (target.startsWith("./src/") && target.endsWith(".ts")) return "source-ts";
+  if (target.startsWith("./src/") && target.endsWith(".mjs")) return "source-mjs";
+  if (target.startsWith("./dist/") && target.endsWith(".d.ts")) return "dist-dts";
+  if (target.startsWith("./dist/") && target.endsWith(".js")) return "dist-js";
+  if (target.startsWith("./dist/") && target.endsWith(".mjs")) return "dist-mjs";
+  if (target.startsWith("./") && !target.includes("..") && target.endsWith(".json")) {
+    return "json-asset";
+  }
+  if (target.startsWith("./")) return "relative-other";
+  return "specifier-other";
+};
+
+const exportEntryKind = (targetKinds) => {
+  if (targetKinds.length === 0) return "empty";
+  if (targetKinds.every((kind) => kind.startsWith("source-"))) return "source-module";
+  if (targetKinds.every((kind) => kind.startsWith("dist-"))) return "dist-module";
+  if (targetKinds.every((kind) => kind === "json-asset")) return "json-asset";
+  return "mixed";
+};
+
+const exportSetForManifest = (manifest) => {
+  const exportsValue = manifest.exports ?? manifest.main;
+  const entries =
+    typeof exportsValue === "string"
+      ? [[".", exportsValue]]
+      : exportsValue !== null && typeof exportsValue === "object"
+        ? Object.entries(exportsValue)
+        : [];
+  return Object.fromEntries(
+    entries
+      .map(([subpath, value]) => {
+        const targets = collectExportTargetStrings(value).sort((left, right) =>
+          left.localeCompare(right),
+        );
+        const targetKinds = [...new Set(targets.map(exportTargetKind))].sort((left, right) =>
+          left.localeCompare(right),
+        );
+        return [
+          subpath,
+          {
+            targetKinds,
+            entryKind: exportEntryKind(targetKinds),
+          },
+        ];
+      })
+      .sort(([left], [right]) => left.localeCompare(right)),
+  );
+};
+
+const readPackageJsonProjection = (manifestPath) => {
+  if (typeof manifestPath !== "string") return { status: "unavailable" };
+  if (!fs.existsSync(manifestPath)) return { status: "missing", manifestPath };
+  try {
+    const manifest = readJson(manifestPath);
+    return {
+      status: "available",
+      manifestPath,
+      packageName: manifest.name,
+      exports: exportSetForManifest(manifest),
+    };
+  } catch (error) {
+    return {
+      status: "failed",
+      manifestPath,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+};
+
+const readTarballPackageJsonProjection = (tarball) => {
+  if (typeof tarball !== "string" || tarball.length === 0) {
+    return { status: "unavailable" };
+  }
+  if (!fs.existsSync(tarball)) return { status: "missing", tarball };
+  const tmp = fs.mkdtempSync(path.join(fs.realpathSync("/tmp"), "agentos-export-tarball-"));
+  try {
+    const result = spawnSync("tar", ["-xzf", tarball, "-C", tmp, "package/package.json"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.status !== 0) {
+      return {
+        status: "failed",
+        tarball,
+        error: result.stderr.trim() || result.stdout.trim() || `tar exited ${result.status}`,
+      };
+    }
+    const projection = readPackageJsonProjection(path.join(tmp, "package", "package.json"));
+    return { ...projection, manifestPath: "package/package.json", tarball };
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+};
+
+const sortedExportKeys = (exports) =>
+  Object.keys(exports ?? {}).sort((left, right) => left.localeCompare(right));
+
+const compareSubpathSets = (leftExports, rightExports) => {
+  const left = new Set(sortedExportKeys(leftExports));
+  const right = new Set(sortedExportKeys(rightExports));
+  return {
+    missing: [...left].filter((subpath) => !right.has(subpath)),
+    extra: [...right].filter((subpath) => !left.has(subpath)),
+  };
+};
+
+const expectedPackedKindForSource = (sourceKind) => {
+  if (sourceKind === "source-module") return "dist-module";
+  return sourceKind;
+};
+
+const compareSourcePackedExports = (source, packed) => {
+  const subpaths = compareSubpathSets(source.exports, packed.exports);
+  const targetKindDrift = [];
+  for (const subpath of sortedExportKeys(source.exports)) {
+    if (packed.exports?.[subpath] === undefined) continue;
+    const expected = expectedPackedKindForSource(source.exports[subpath].entryKind);
+    const actual = packed.exports[subpath].entryKind;
+    if (actual !== expected) {
+      targetKindDrift.push({
+        subpath,
+        sourceKind: source.exports[subpath].entryKind,
+        expectedPackedKind: expected,
+        actualPackedKind: actual,
+      });
+    }
+  }
+  return {
+    status:
+      subpaths.missing.length === 0 && subpaths.extra.length === 0 && targetKindDrift.length === 0
+        ? "pass"
+        : "fail",
+    subpaths,
+    targetKindDrift,
+  };
+};
+
+const compareEquivalentExports = (left, right) => {
+  const subpaths = compareSubpathSets(left.exports, right.exports);
+  const targetKindDrift = [];
+  for (const subpath of sortedExportKeys(left.exports)) {
+    if (right.exports?.[subpath] === undefined) continue;
+    const leftKind = left.exports[subpath].entryKind;
+    const rightKind = right.exports[subpath].entryKind;
+    if (leftKind !== rightKind) {
+      targetKindDrift.push({ subpath, leftKind, rightKind });
+    }
+  }
+  return {
+    status:
+      subpaths.missing.length === 0 && subpaths.extra.length === 0 && targetKindDrift.length === 0
+        ? "pass"
+        : "fail",
+    subpaths,
+    targetKindDrift,
+  };
+};
+
+const exportFailure = (code, packageName, comparison, detail = {}) => ({
+  code,
+  packageName,
+  comparison,
+  ...detail,
+});
+
+const exportEquivalenceForPackage = (entry, options = {}) => {
+  const source = readPackageJsonProjection(
+    sourceManifestPathForPackage(entry.packageName, options.sourceRoot),
+  );
+  const packed = readTarballPackageJsonProjection(entry.tarball);
+  const installed = readPackageJsonProjection(entry.installedManifestPath);
+  const failures = [];
+  const comparisons = {};
+  if (packed.status !== "available") {
+    failures.push(
+      exportFailure("export_packed_manifest_unavailable", entry.packageName, "packed", {
+        status: packed.status,
+        error: packed.error,
+      }),
+    );
+  }
+  if (entry.installedManifestPath !== undefined && installed.status !== "available") {
+    failures.push(
+      exportFailure("export_installed_manifest_unavailable", entry.packageName, "installed", {
+        status: installed.status,
+        error: installed.error,
+      }),
+    );
+  }
+  if (source.status === "available" && packed.status === "available") {
+    const comparison = compareSourcePackedExports(source, packed);
+    comparisons.sourcePacked = comparison;
+    if (comparison.subpaths.missing.length > 0 || comparison.subpaths.extra.length > 0) {
+      failures.push(
+        exportFailure("export_source_packed_subpath_drift", entry.packageName, "source_packed", {
+          missingSubpaths: comparison.subpaths.missing,
+          extraSubpaths: comparison.subpaths.extra,
+        }),
+      );
+    }
+    if (comparison.targetKindDrift.length > 0) {
+      failures.push(
+        exportFailure(
+          "export_source_packed_target_kind_drift",
+          entry.packageName,
+          "source_packed",
+          { targetKindDrift: comparison.targetKindDrift },
+        ),
+      );
+    }
+  }
+  if (packed.status === "available" && installed.status === "available") {
+    const comparison = compareEquivalentExports(packed, installed);
+    comparisons.packedInstalled = comparison;
+    if (comparison.subpaths.missing.length > 0 || comparison.subpaths.extra.length > 0) {
+      failures.push(
+        exportFailure(
+          "export_packed_installed_subpath_drift",
+          entry.packageName,
+          "packed_installed",
+          {
+            missingSubpaths: comparison.subpaths.missing,
+            extraSubpaths: comparison.subpaths.extra,
+          },
+        ),
+      );
+    }
+    if (comparison.targetKindDrift.length > 0) {
+      failures.push(
+        exportFailure(
+          "export_packed_installed_target_kind_drift",
+          entry.packageName,
+          "packed_installed",
+          { targetKindDrift: comparison.targetKindDrift },
+        ),
+      );
+    }
+  }
+  return {
+    packageName: entry.packageName,
+    source,
+    packed,
+    ...(entry.installedManifestPath === undefined ? {} : { installed }),
+    comparisons,
+    status: failures.length === 0 ? "verified" : "failed",
+    failures,
+  };
+};
+
+export const exportEquivalenceProjection = (entries, options = {}) => {
+  const packages = entries
+    .map((entry) => exportEquivalenceForPackage(entry, options))
+    .sort((left, right) => left.packageName.localeCompare(right.packageName));
+  const failures = packages.flatMap((pkg) => pkg.failures);
+  return {
+    status: packages.length === 0 ? "not_checked" : failures.length === 0 ? "verified" : "failed",
+    packagesChecked: packages.length,
+    packages,
+    failures,
+  };
+};
+
+export const exportEquivalenceForInstallManifest = (manifest, options = {}) =>
+  exportEquivalenceProjection(
+    Object.entries(manifest.tarballs ?? {}).map(([packageName, entry]) => ({
+      packageName,
+      tarball: optionalFileSpecPath(entry?.spec),
+    })),
+    options,
+  );
+
 const packageOverlayRows = (consumerRoot, marker) => {
   const nodeModules = path.join(consumerRoot, "node_modules");
   return Object.entries(marker.packages ?? {})
@@ -336,6 +712,7 @@ const packageOverlayRows = (consumerRoot, marker) => {
       const tarballExists = tarball.length > 0 && fs.existsSync(tarball);
       const expectedSha = typeof record.sha256 === "string" ? record.sha256 : undefined;
       const actualSha = tarballExists ? sha256File(tarball) : undefined;
+      const requiresSha = marker.artifact?.kind === "install-manifest-overlay";
       return {
         packageName,
         target: record.target,
@@ -343,9 +720,13 @@ const packageOverlayRows = (consumerRoot, marker) => {
         targetStatus,
         tarball,
         tarballStatus: tarballExists
-          ? expectedSha === undefined || expectedSha === actualSha
-            ? "verified"
-            : "sha_mismatch"
+          ? expectedSha === undefined
+            ? requiresSha
+              ? "sha_missing"
+              : "verified"
+            : expectedSha === actualSha
+              ? "verified"
+              : "sha_mismatch"
           : "missing",
         sha256: expectedSha,
       };
@@ -457,6 +838,38 @@ const consumerGateIssue = (code, severity, dimension, message, detail = {}) => (
 const consumerOverlayGate = (status) => {
   const hardFailures = [];
   const signals = [];
+  if (status.workspaceOverlay?.status === "invalid") {
+    hardFailures.push(
+      consumerGateIssue(
+        "workspace_layout_invalid",
+        "hard",
+        "workspace_layout",
+        "consumer workspace manifest could not be projected",
+        {
+          manifestPath: status.workspaceOverlay.manifestPath,
+          error: status.workspaceOverlay.error,
+        },
+      ),
+    );
+  }
+  for (const root of status.workspaceOverlay?.roots ?? []) {
+    if (root.relativePath === ".") continue;
+    if (root.gate?.status !== "pass") {
+      hardFailures.push(
+        consumerGateIssue(
+          "workspace_consumer_root_failed",
+          "hard",
+          "workspace_resolver",
+          `workspace consumer root ${root.relativePath} does not have a passing local overlay`,
+          {
+            relativePath: root.relativePath,
+            packageName: root.packageName,
+            gate: root.gate,
+          },
+        ),
+      );
+    }
+  }
   if (status.localOverlay.status === "missing") {
     hardFailures.push(
       consumerGateIssue(
@@ -468,13 +881,25 @@ const consumerOverlayGate = (status) => {
       ),
     );
   }
-  if (status.localOverlay.status === "partial") {
+  for (const failure of status.packageIntegrity.failures ?? []) {
     hardFailures.push(
       consumerGateIssue(
-        "local_overlay_partial",
+        failure.code,
         "hard",
         "package_integrity",
-        "local consumer overlay package installation is partial",
+        failure.message ?? `local consumer overlay package integrity failed: ${failure.code}`,
+        failure,
+      ),
+    );
+  }
+  for (const failure of status.exportEquivalence?.failures ?? []) {
+    hardFailures.push(
+      consumerGateIssue(
+        failure.code,
+        "hard",
+        "export_equivalence",
+        `local consumer overlay export equivalence failed: ${failure.code}`,
+        failure,
       ),
     );
   }
@@ -513,41 +938,6 @@ const consumerOverlayGate = (status) => {
       ),
     );
   }
-  for (const pkg of status.localOverlay.packages ?? []) {
-    if (pkg.targetStatus === "missing") {
-      hardFailures.push(
-        consumerGateIssue(
-          "local_overlay_package_missing",
-          "hard",
-          "package_integrity",
-          `${pkg.packageName} is missing from the consumer overlay`,
-          { packageName: pkg.packageName },
-        ),
-      );
-    }
-    if (pkg.targetStatus === "symlink") {
-      hardFailures.push(
-        consumerGateIssue(
-          "local_overlay_package_symlink",
-          "hard",
-          "package_integrity",
-          `${pkg.packageName} is a symlink, not packed package content`,
-          { packageName: pkg.packageName },
-        ),
-      );
-    }
-    if (pkg.tarballStatus !== "verified") {
-      hardFailures.push(
-        consumerGateIssue(
-          "local_overlay_tarball_not_verified",
-          "hard",
-          "package_integrity",
-          `${pkg.packageName} tarball status is ${pkg.tarballStatus}`,
-          { packageName: pkg.packageName, tarballStatus: pkg.tarballStatus },
-        ),
-      );
-    }
-  }
   if (status.npmLatest.status === "not_checked") {
     signals.push(
       consumerGateIssue(
@@ -585,7 +975,7 @@ const withConsumerGate = (status) => ({
   gate: consumerOverlayGate(status),
 });
 
-export const consumerStatusData = (consumerRoot, options = {}) => {
+const consumerStatusDataForRoot = (consumerRoot, options = {}) => {
   const metadata = packageMetadata(options.packageRoot);
   const markerPath = localConsumerMarkerPath(consumerRoot);
   const currentSource =
@@ -606,6 +996,19 @@ export const consumerStatusData = (consumerRoot, options = {}) => {
   }
   const marker = readJson(markerPath);
   const packages = packageOverlayRows(consumerRoot, marker);
+  const exportEquivalence = exportEquivalenceProjection(
+    packages.map((pkg) => ({
+      packageName: pkg.packageName,
+      tarball: pkg.tarball,
+      installedManifestPath: path.join(
+        consumerRoot,
+        "node_modules",
+        ...pkg.packageName.split("/"),
+        "package.json",
+      ),
+    })),
+    { sourceRoot: options.sourceRoot },
+  );
   const sourceStatus = overlaySourceStatus(marker, currentSource);
   const packageIntegrity = packageIntegrityFor(marker, packages);
   const sourceFreshness = sourceFreshnessFor(marker, currentSource);
@@ -623,6 +1026,7 @@ export const consumerStatusData = (consumerRoot, options = {}) => {
       packages,
     },
     packageIntegrity,
+    exportEquivalence,
     sourceFreshness,
     source: {
       ...(currentSource === undefined ? {} : { current: currentSource }),
@@ -643,12 +1047,62 @@ export const consumerStatusData = (consumerRoot, options = {}) => {
   });
 };
 
+const workspaceRootStatusSummary = (root, status) => ({
+  kind: root.kind,
+  relativePath: root.relativePath,
+  consumerRoot: root.consumerRoot,
+  ...(root.packageName === undefined ? {} : { packageName: root.packageName }),
+  truthMode: status.truthMode,
+  localOverlay: status.localOverlay,
+  packageIntegrity: status.packageIntegrity,
+  exportEquivalence: status.exportEquivalence,
+  sourceFreshness: status.sourceFreshness,
+  packageVersion: status.packageVersion,
+  gate: status.gate,
+});
+
+export const consumerStatusData = (consumerRoot, options = {}) => {
+  const status = consumerStatusDataForRoot(consumerRoot, options);
+  if (options.workspace === false) return status;
+  const layout = consumerWorkspaceLayout(consumerRoot);
+  if (layout.status === "not_workspace") return status;
+  const roots =
+    layout.status === "invalid"
+      ? [workspaceRootStatusSummary(layout.roots[0], status)]
+      : layout.roots.map((root) =>
+          workspaceRootStatusSummary(
+            root,
+            root.relativePath === "."
+              ? status
+              : consumerStatusDataForRoot(root.consumerRoot, options),
+          ),
+        );
+  const workspaceStatus =
+    layout.status === "invalid"
+      ? "invalid"
+      : roots.every((root) => root.gate.status === "pass")
+        ? "verified"
+        : "failed";
+  return withConsumerGate({
+    ...status,
+    workspaceOverlay: {
+      status: workspaceStatus,
+      manifestPath: layout.manifestPath,
+      roots,
+      ...(layout.error === undefined ? {} : { error: layout.error }),
+    },
+  });
+};
+
 const printConsumerStatus = (status) => {
   console.log(`consumer: ${status.consumerRoot}`);
   console.log(`marker: ${status.markerPath}`);
   console.log(`truth mode: ${status.truthMode}`);
   console.log(`local overlay: ${status.localOverlay.status}`);
   console.log(`package integrity: ${status.packageIntegrity.status}`);
+  if (status.exportEquivalence !== undefined) {
+    console.log(`export equivalence: ${status.exportEquivalence.status}`);
+  }
   if (status.sourceFreshness !== undefined) {
     console.log(`source freshness: ${status.sourceFreshness.status}`);
   }
@@ -659,6 +1113,14 @@ const printConsumerStatus = (status) => {
     `package version: overlay=${status.packageVersion.overlay ?? "none"} release=${status.packageVersion.release} status=${status.packageVersion.status ?? "none"}`,
   );
   console.log(`npm latest: ${status.npmLatest.status}`);
+  if (status.workspaceOverlay !== undefined) {
+    console.log(`workspace overlay: ${status.workspaceOverlay.status}`);
+    for (const root of status.workspaceOverlay.roots ?? []) {
+      console.log(
+        `workspace ${root.relativePath}: gate=${root.gate.status} overlay=${root.localOverlay.status}`,
+      );
+    }
+  }
   console.log(`gate: ${status.gate.status}`);
   for (const pkg of status.localOverlay.packages ?? []) {
     console.log(
@@ -695,40 +1157,50 @@ export const installConsumer = async (rawArgs, context = {}) => {
   const args = parseArgs(rawArgs);
   const consumerRoot = resolveConsumerRoot(positionalArgs(args)[0]);
   const manifestPath = await installManifestPathForArgs(args, context);
-  const snapshot = snapshotFiles(consumerManifestFiles(consumerRoot));
+  const workspaceLayout = consumerWorkspaceLayout(consumerRoot);
+  if (workspaceLayout.status === "invalid") {
+    fail(`${consumerRoot}: ${workspaceLayout.error}`);
+  }
+  const snapshot = snapshotFiles(consumerWorkspaceManifestFiles(workspaceLayout));
   const { manifest } = readInstallManifest(manifestPath);
   const entries = tarballPackageEntries(manifest);
-  const nodeModules = nodeModulesRoot(consumerRoot, { install: !boolArg(args, "no-install") });
-  const packages = {};
-  for (const entry of entries) {
-    const target = packageTargetDir(nodeModules, entry.packageName);
-    unpackTarballInto(entry.tarball, target);
-    packages[entry.packageName] = {
-      target: path.relative(consumerRoot, target).split(path.sep).join("/"),
-      tarball: entry.tarball,
-      sha256: entry.sha256,
-    };
-  }
+  nodeModulesRoot(consumerRoot, { install: !boolArg(args, "no-install") });
   const source =
     typeof context.sourceRoot === "string"
       ? sourceIdentityFor(context.sourceRoot)
       : (manifest.source ?? undefined);
-  writeJson(localConsumerMarkerPath(consumerRoot), {
-    schemaVersion: 1,
-    generatedBy: "agentos consumer install",
-    installedAt: new Date().toISOString(),
-    consumerRoot,
-    ...(source === undefined ? {} : { source }),
-    packageVersion: manifest.version,
-    artifact: markerArtifact(manifestPath, manifest),
-    packages,
-  });
+  const installedAt = new Date().toISOString();
+  for (const root of workspaceLayout.roots) {
+    const nodeModules = path.join(root.consumerRoot, "node_modules");
+    const packages = {};
+    for (const entry of entries) {
+      const target = packageTargetDir(nodeModules, entry.packageName);
+      unpackTarballInto(entry.tarball, target);
+      packages[entry.packageName] = {
+        target: path.relative(root.consumerRoot, target).split(path.sep).join("/"),
+        tarball: entry.tarball,
+        sha256: entry.sha256,
+      };
+    }
+    writeJson(localConsumerMarkerPath(root.consumerRoot), {
+      schemaVersion: 1,
+      generatedBy: "agentos consumer install",
+      installedAt,
+      consumerRoot: root.consumerRoot,
+      ...(source === undefined ? {} : { source }),
+      packageVersion: manifest.version,
+      artifact: markerArtifact(manifestPath, manifest),
+      packages,
+    });
+  }
   assertSnapshotUnchanged(snapshot, "agentos consumer install");
   const status = consumerStatusData(consumerRoot, { sourceRoot: context.sourceRoot });
   if (boolArg(args, "json")) {
     console.log(JSON.stringify(status, null, 2));
   } else {
-    console.log(`installed ${entries.length} local agentOS packages into ${consumerRoot}`);
+    console.log(
+      `installed ${entries.length} local agentOS packages into ${workspaceLayout.roots.length} consumer root(s)`,
+    );
     console.log(
       `wrote ${path.relative(consumerRoot, localConsumerMarkerPath(consumerRoot)).split(path.sep).join("/")}`,
     );
@@ -790,7 +1262,14 @@ export const restoreConsumer = (rawArgs) => {
   }
   fs.rmSync(markerPath, { force: true });
   if (!boolArg(args, "no-install")) {
-    run("npm", ["install"], { cwd: consumerRoot });
+    const installCommand = consumerInstallCommand(consumerRoot);
+    if (installCommand === null) {
+      fail(`${consumerRoot}: no package manager/lockfile was detected for consumer restore`);
+    }
+    run(installCommand.cmd, installCommand.args, {
+      cwd: consumerRoot,
+      env: installCommand.env,
+    });
   }
   assertSnapshotUnchanged(snapshot, "agentos consumer restore");
   const result = { schemaVersion: 1, restoredPackages: packageNames };