@clossys/launcher 0.1.1 → 0.1.5

package/src/core.ts

@@ -1,11 +1,16 @@
 import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
+  ApplyWorkspaceOptions,
   CommandResult,
   CwdObservation,
+  DependencyBucket,
   HubDocument,
   HubHealthReport,
   InventoryObservation,
+  InventoryValidationEntry,
+  InventoryValidationReport,
+  PinFinding,
   WorkspaceApplyResult,
   WorkspaceDecision,
   WorkspaceHost,
@@ -14,12 +19,20 @@ import type {
   WorkspacePlanCreate,
   WorkspaceRefusal,
 } from "./types.js";
+import { composeSkills, type SkillCompositionResult } from "./skills.js";
 
 export const DEFAULT_REPOSITORY_NAME = "workspace";
 export const WORKSPACE_MARKER_REL = ".clossys/workspace.json";
 export const WORKSPACE_INVENTORY_REL = ".clossys/inventory.json";
 export const ADVISOR_PACKAGE = "@clossys/advisor";
 
+const DEPENDENCY_BUCKETS: readonly DependencyBucket[] = [
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies",
+];
+
 const OWNER = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
 const REPO = /^[A-Za-z0-9._-]+$/;
 const SKELETON_FILES = [
@@ -33,6 +46,31 @@ const SKELETON_FILES = [
 /** Written at generate time so this package never ships a nested AGENTS.md. */
 export const CONSUMER_AGENTS_MD = `# Account workspace
 
+This folder is the account hub for Foundry packages.
+
+After \`npx @clossys/launcher\`, the same \`@clossys-*\` team is composed in
+every inventoried checkout beside this hub. Talk with \`@clossys-advisor\` and
+\`@clossys-<package>\` here or in a product repository. A missing \`@\` mention
+is not how we signal incompatibility — \`@clossys-advisor\` is the hiring check.
+
+Run \`npx @clossys/launcher\` again for hub health and to refresh voices on
+clones next to the hub, not as how you talk to packages.
+
+Advisor is read-only until the sponsor approves a next action.
+`;
+
+/** Canned guidance for inventoried product checkouts (not the hub). */
+export const SISTER_CONSUMER_AGENTS_MD = `# Product repository
+
+This repository is part of the same account engagement. The same
+\`@clossys-<package>\` team is here for intro and questions;
+\`@clossys-advisor\` decides hiring and compatibility. This folder is not the
+hub — engines are hired per repository, not dumped here.
+`;
+
+/** Previous generate-time guidance; used to refresh stale hub AGENTS.md on resume. */
+export const LEGACY_CONSUMER_AGENTS_MD = `# Account workspace
+
 This repository is the account hub for Foundry packages. It inventories
 where packages are installed and coordinates engagement. It is not a
 product application and does not need the whole catalogue installed here.
@@ -89,6 +127,34 @@ export function parseGitHubRemote(url: string): { owner: string; repository: str
   }
 }
 
+function readJson(host: WorkspaceHost, path: string): unknown {
+  const raw = host.readText(path);
+  if (raw === null) return undefined;
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Tiny semver-ish compare of `a` versus `b`: -1 older, 0 equal, 1 newer. Unparseable versions are indeterminate (null). */
+function compareVersions(a: string, b: string): -1 | 0 | 1 | null {
+  const parse = (version: string): readonly number[] | null => {
+    const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)$/);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+  };
+  const left = parse(a);
+  const right = parse(b);
+  if (!left || !right) return null;
+  for (let index = 0; index < 3; index += 1) {
+    const l = left[index] ?? 0;
+    const r = right[index] ?? 0;
+    if (l < r) return -1;
+    if (l > r) return 1;
+  }
+  return 0;
+}
+
 /** True when the marker is a v1 account-hub document. */
 export function isHubDocument(value: unknown): value is HubDocument {
   if (!isRecord(value) || value.schemaVersion !== 1 || value.kind !== "account-hub") return false;
@@ -159,6 +225,12 @@ function commandAvailable(host: WorkspaceHost, command: string): boolean {
   return result.status === 0;
 }
 
+/** True when the tree already pins Advisor in some bucket, so adopt would not need a new version. */
+export function hasAdvisorPin(manifest: unknown): boolean {
+  if (!isRecord(manifest)) return false;
+  return DEPENDENCY_BUCKETS.some((bucket) => clossysNames(manifest[bucket], new Set()) !== undefined);
+}
+
 /** Collects GitHub owner, cwd shape, default-hub presence, and the public Advisor pin. */
 export function observeWorkspace(host: WorkspaceHost): WorkspaceObservation {
   const cwd = host.cwd;
@@ -196,9 +268,14 @@ export function observeWorkspace(host: WorkspaceHost): WorkspaceObservation {
     const viewed = host.run("gh", ["repo", "view", `${ownerGuess}/${DEFAULT_REPOSITORY_NAME}`, "--json", "name"]);
     if (viewed.status === 0) remoteDefaultHub = { owner: ownerGuess, repository: DEFAULT_REPOSITORY_NAME };
   }
-  const viewedAdvisor = host.run("npm", ["view", ADVISOR_PACKAGE, "version"]);
-  const version = viewedAdvisor.stdout.trim();
-  if (viewedAdvisor.status === 0 && /^\d+\.\d+\.\d+$/.test(version)) advisorVersion = version;
+  // Skip the registry read when the tree already pins Advisor in some bucket:
+  // adopt leaves an existing pin alone, so no live version is needed to plan it.
+  const manifestPinsAdvisor = hasAdvisorPin(readJson(host, join(cwd, "package.json")));
+  if (!manifestPinsAdvisor) {
+    const viewedAdvisor = host.run("npm", ["view", ADVISOR_PACKAGE, "version"]);
+    const version = viewedAdvisor.stdout.trim();
+    if (viewedAdvisor.status === 0 && /^\d+\.\d+\.\d+$/.test(version)) advisorVersion = version;
+  }
 
   const cwdObservation: CwdObservation = {
     absolutePath: cwd,
@@ -245,19 +322,43 @@ function resolveOwner(observation: WorkspaceObservation, host: WorkspaceHost): {
  * Decides create, resume, or adopt from a cwd observation.
  * Appointing means: run this from the GitHub repository that should own the hub.
  */
+export function readInventoryRepositories(host: WorkspaceHost, source: string, label: string): readonly string[] {
+  const raw = host.readText(source);
+  if (raw === null) return [];
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!isRecord(parsed) || !Array.isArray(parsed.repositories)) return [];
+    return parsed.repositories.map((entry) => {
+      if (isRecord(entry) && isText(entry.id)) return entry.id.trim();
+      return "";
+    });
+  } catch {
+    throw new Error(`${label} is not readable inventory JSON (schemaVersion 1, repositories array)`);
+  }
+}
+
+/**
+ * Resolves which repositories the adopt plan inventories. When the on-disk hub
+ * inventory is populated AND --inventory is supplied, the two are merged by id:
+ * on-disk entries keep their order, ids not already on disk are appended in
+ * supplied-file order, and the first occurrence of an id wins; the plan carries
+ * the merged ids for applyWorkspacePlan to write. When both are empty or
+ * missing, adopt refuses rather than appointing an inventory-less hub.
+ */
 function resolveAdoptInventory(
   host: WorkspaceHost,
   cwd: CwdObservation,
   inventoryPath: string | undefined,
-): { inventorySource?: string } | WorkspaceRefusal {
-  if (cwd.inventory?.status === "populated") return {};
+): { inventorySource?: string; mergedInventoryIds?: readonly string[] } | WorkspaceRefusal {
   const trimmed = inventoryPath?.trim();
-  if (!trimmed) {
+  const onDiskPopulated = cwd.inventory?.status === "populated";
+  if (!onDiskPopulated && !trimmed) {
     return refuse(
       "violated",
       "appointing requires a populated generated hub inventory (packed template skeleton/.clossys/inventory.json; the generated path does not ship), or --inventory <path> to a populated inventory document",
     );
   }
+  if (!trimmed) return {};
   const resolved = resolve(cwd.absolutePath, trimmed);
   const imported = inspectInventory(host.readText(resolved));
   if (imported.status !== "populated") {
@@ -266,7 +367,22 @@ function resolveAdoptInventory(
       "--inventory must point at a populated inventory document (schemaVersion 1, nonempty repositories)",
     );
   }
-  return { inventorySource: resolved };
+  if (!onDiskPopulated) return { inventorySource: resolved };
+  const merged: string[] = [];
+  const seen = new Set<string>();
+  for (const id of readInventoryRepositories(host, join(cwd.absolutePath, WORKSPACE_INVENTORY_REL), "the on-disk hub inventory")) {
+    if (id !== "" && !seen.has(id)) {
+      seen.add(id);
+      merged.push(id);
+    }
+  }
+  for (const id of readInventoryRepositories(host, resolved, "--inventory")) {
+    if (id !== "" && !seen.has(id)) {
+      seen.add(id);
+      merged.push(id);
+    }
+  }
+  return { mergedInventoryIds: merged };
 }
 
 export function planWorkspace(
@@ -275,6 +391,20 @@ export function planWorkspace(
   options: { inventoryPath?: string } = {},
 ): WorkspaceDecision {
   const { cwd } = observation;
+  const envOwner = observation.envOwner ?? (host.env.CLOSSYS_OWNER?.trim() || undefined);
+  if (
+    envOwner !== undefined &&
+    !cwd.looksLikeFoundry &&
+    cwd.hub === undefined &&
+    cwd.git &&
+    cwd.githubOwner !== undefined &&
+    cwd.githubOwner !== envOwner
+  ) {
+    return refuse(
+      "violated",
+      `CLOSSYS_OWNER is "${envOwner}" but the github.com origin here is owned by "${cwd.githubOwner}"; refusing to appoint a marker for the wrong account`,
+    );
+  }
   if (cwd.looksLikeFoundry) {
     return refuse(
       "violated",
@@ -303,6 +433,7 @@ export function planWorkspace(
       directory: cwd.absolutePath,
       advisorVersion: observation.advisorVersion,
       ...(imported.inventorySource === undefined ? {} : { inventorySource: imported.inventorySource }),
+      ...(imported.mergedInventoryIds === undefined ? {} : { mergedInventoryIds: imported.mergedInventoryIds }),
     };
   }
   if (cwd.git) {
@@ -344,7 +475,7 @@ function containedPath(root: string, relativePath: string): string {
   const resolved = resolve(root, relativePath);
   const prefix = root.endsWith(sep) ? root : `${root}${sep}`;
   if (resolved !== root && !resolved.startsWith(prefix)) {
-    throw new Error(`refusing to write outside the hub directory: ${relativePath}`);
+    throw new Error(`refusing to write outside the workspace directory: ${relativePath}`);
   }
   return resolved;
 }
@@ -404,9 +535,8 @@ function mergeAdvisorPin(
     throw new Error("existing package.json is unreadable JSON");
   }
   const extra = new Set<string>();
-  const inDependencies = clossysNames(manifest.dependencies, extra);
-  const inDevDependencies = clossysNames(manifest.devDependencies, extra);
-  if (inDependencies !== undefined || inDevDependencies !== undefined) return;
+  const pinnedSomewhere = DEPENDENCY_BUCKETS.some((bucket) => clossysNames(manifest[bucket], extra) !== undefined);
+  if (pinnedSomewhere) return;
   const devDependencies = isRecord(manifest.devDependencies) ? { ...manifest.devDependencies } : {};
   devDependencies[ADVISOR_PACKAGE] = advisorVersion;
   manifest.devDependencies = devDependencies;
@@ -423,7 +553,30 @@ function copySkeleton(host: WorkspaceHost, skeletonRoot: string, plan: Workspace
   writeSkeletonFile(host, plan.directory, "CLAUDE.md", CONSUMER_CLAUDE_MD);
 }
 
+/** Refuses adopt when the working tree has uncommitted changes; names a non-github.com remote host. */
+function assertCleanTree(host: WorkspaceHost, directory: string): void {
+  const status = host.run("git", ["status", "--porcelain"], { cwd: directory });
+  if (status.status === 0 && status.stdout.trim() !== "") {
+    const origin = host.run("git", ["remote", "get-url", "origin"], { cwd: directory }).stdout.trim();
+    let where = "this checkout";
+    if (origin !== "") {
+      try {
+        const parsed = new URL(origin);
+        if (parsed.protocol === "ssh:" || parsed.protocol === "https:" || parsed.protocol === "http:") {
+          where = `the repository on ${parsed.hostname}`;
+        }
+      } catch {
+        /* ssh form or unparsable; keep the generic host */
+      }
+    }
+    throw new Error(
+      `${where} has uncommitted changes (git status --porcelain is nonempty); commit or stash them before appointing it as the account hub`,
+    );
+  }
+}
+
 function adoptHubFiles(host: WorkspaceHost, skeletonRoot: string, plan: WorkspacePlan & { advisorVersion: string }): void {
+  assertCleanTree(host, plan.directory);
   const marker = {
     schemaVersion: 1,
     kind: "account-hub",
@@ -431,7 +584,15 @@ function adoptHubFiles(host: WorkspaceHost, skeletonRoot: string, plan: Workspac
     repository: `${plan.owner}/${plan.repository}`,
   };
   writeSkeletonFile(host, plan.directory, WORKSPACE_MARKER_REL, `${JSON.stringify(marker, null, 2)}\n`);
-  if ("inventorySource" in plan && typeof plan.inventorySource === "string") {
+  if ("mergedInventoryIds" in plan && Array.isArray(plan.mergedInventoryIds)) {
+    const document = { schemaVersion: 1, repositories: plan.mergedInventoryIds.map((id) => ({ id })) };
+    writeSkeletonFile(
+      host,
+      plan.directory,
+      WORKSPACE_INVENTORY_REL,
+      `${JSON.stringify(document, null, 2)}\n`,
+    );
+  } else if ("inventorySource" in plan && typeof plan.inventorySource === "string") {
     const raw = host.readText(plan.inventorySource);
     if (raw === null || inspectInventory(raw).status !== "populated") {
       throw new Error("inventory source is not a populated inventory document");
@@ -440,6 +601,8 @@ function adoptHubFiles(host: WorkspaceHost, skeletonRoot: string, plan: Workspac
   }
   if (host.readText(join(plan.directory, "AGENTS.md")) === null) {
     writeSkeletonFile(host, plan.directory, "AGENTS.md", CONSUMER_AGENTS_MD);
+  } else {
+    writeConsumerAgentsIfNeeded(host, plan.directory);
   }
   if (host.readText(join(plan.directory, "CLAUDE.md")) === null) {
     writeSkeletonFile(host, plan.directory, "CLAUDE.md", CONSUMER_CLAUDE_MD);
@@ -461,51 +624,97 @@ function requireZero(result: CommandResult, label: string): void {
   }
 }
 
-/** Read-only pin and inventory report. Does not install or uninstall. */
+/**
+ * Read-only pin and inventory report. Does not install or uninstall. Scans all
+ * four dependency buckets; grades each pinned advisor version against the live
+ * registry version, marking a pin older than live as a stale-pin finding and a
+ * degraded report.
+ */
 export function reportHubHealth(host: WorkspaceHost, directory: string, liveAdvisorVersion?: string): HubHealthReport {
   const extra = new Set<string>();
-  let dependencies: string | undefined;
-  let devDependencies: string | undefined;
+  const pins: Partial<Record<DependencyBucket, string>> = {};
   const manifestRaw = host.readText(join(directory, "package.json"));
   if (manifestRaw !== null) {
     try {
       const parsed: unknown = JSON.parse(manifestRaw);
       if (isRecord(parsed)) {
-        dependencies = clossysNames(parsed.dependencies, extra);
-        devDependencies = clossysNames(parsed.devDependencies, extra);
+        for (const bucket of DEPENDENCY_BUCKETS) {
+          const pin = clossysNames(parsed[bucket], extra);
+          if (pin !== undefined) pins[bucket] = pin;
+        }
       }
     } catch {
       /* unreadable manifest is reported as missing pins */
     }
   }
+  const pinFindings: PinFinding[] = Object.entries(pins).flatMap(([bucket, pinned]): PinFinding[] => {
+    if (liveAdvisorVersion === undefined) return [];
+    const comparison = compareVersions(pinned, liveAdvisorVersion);
+    if (comparison === null) {
+      return [{ bucket: bucket as DependencyBucket, pinned, grade: "indeterminate", note: `cannot compare ${pinned} with live ${liveAdvisorVersion}` }];
+    }
+    return comparison < 0
+      ? [{ bucket: bucket as DependencyBucket, pinned, grade: "stale", note: `pinned ${pinned} is older than live ${liveAdvisorVersion}` }]
+      : [];
+  });
   return {
     marker: readHub(host, directory) === undefined ? "missing" : "present",
     inventory: inspectInventory(host.readText(join(directory, WORKSPACE_INVENTORY_REL))),
     advisorPin: {
-      ...(dependencies === undefined ? {} : { dependencies }),
-      ...(devDependencies === undefined ? {} : { devDependencies }),
+      ...(pins.dependencies === undefined ? {} : { dependencies: pins.dependencies }),
+      ...(pins.devDependencies === undefined ? {} : { devDependencies: pins.devDependencies }),
+      ...(pins.optionalDependencies === undefined ? {} : { optionalDependencies: pins.optionalDependencies }),
+      ...(pins.peerDependencies === undefined ? {} : { peerDependencies: pins.peerDependencies }),
       ...(liveAdvisorVersion === undefined ? {} : { live: liveAdvisorVersion }),
     },
-    dualPin: dependencies !== undefined && devDependencies !== undefined,
+    dualPin: Object.values(pins).filter((value) => value !== undefined).length > 1,
     extraClossys: [...extra].sort(),
+    pinFindings,
+    degraded: pinFindings.some((finding) => finding.grade === "stale"),
   };
 }
 
 export function formatHubHealth(report: HubHealthReport): string {
   const pinParts: string[] = [];
-  if (report.advisorPin.dependencies !== undefined) pinParts.push(`dependencies ${report.advisorPin.dependencies}`);
-  if (report.advisorPin.devDependencies !== undefined) pinParts.push(`devDependencies ${report.advisorPin.devDependencies}`);
+  for (const bucket of DEPENDENCY_BUCKETS) {
+    const pinned = report.advisorPin[bucket];
+    if (pinned !== undefined) pinParts.push(`${bucket} ${pinned}`);
+  }
   const pin = pinParts.length === 0 ? "missing" : pinParts.join(" and ");
   const live = report.advisorPin.live === undefined ? "" : `; live ${report.advisorPin.live}`;
   const extra = report.extraClossys.length === 0 ? "none" : report.extraClossys.join(", ");
   const inventory =
     report.inventory.status === "populated" ? `populated (${report.inventory.count})` : report.inventory.status;
+  const findings = report.pinFindings.map((finding) =>
+    finding.note !== undefined ? `${finding.bucket} ${finding.note}` : `${finding.bucket} ${finding.grade}`,
+  );
+  const findingLine = findings.length === 0 ? "none" : findings.join("; ");
+  const skillParts: string[] = [];
+  if (report.skillComposition !== undefined) {
+    skillParts.push(
+      report.skillComposition.composed.length === 0
+        ? "skills composed: none"
+        : `skills composed: ${report.skillComposition.composed.map((name) => `clossys-${name}`).join(", ")}`,
+    );
+    for (const skip of report.skillComposition.skipped) {
+      skillParts.push(`skill skipped (${skip.packageDir}): ${skip.note}`);
+    }
+    if (report.skillComposition.rosterTargets !== undefined && report.skillComposition.rosterTargets.length > 0) {
+      skillParts.push(`skill roster written: ${report.skillComposition.rosterTargets.join(", ")}`);
+    }
+    for (const skip of report.skillComposition.rosterSkipped ?? []) {
+      skillParts.push(`skill roster skipped (${skip.inventoryId}): ${skip.note}`);
+    }
+  }
   return [
     `hub marker: ${report.marker}`,
     `inventory: ${inventory}`,
     `advisor pin: ${pin}${live}`,
     `dual pin: ${report.dualPin ? "yes" : "no"}`,
     `extra @clossys/*: ${extra}`,
+    `pin findings: ${findingLine}`,
+    `degraded: ${report.degraded ? "yes" : "no"}`,
+    ...(skillParts.length === 0 ? [] : skillParts),
     `health: ${JSON.stringify(report)}`,
   ].join("\n");
 }
@@ -515,8 +724,12 @@ function withHealth(
   directory: string,
   headline: string,
   liveAdvisorVersion?: string,
+  skillComposition?: SkillCompositionResult,
 ): WorkspaceApplyResult {
-  const health = reportHubHealth(host, directory, liveAdvisorVersion);
+  const health: HubHealthReport = {
+    ...reportHubHealth(host, directory, liveAdvisorVersion),
+    ...(skillComposition === undefined ? {} : { skillComposition }),
+  };
   return {
     state: "satisfied",
     message: `${headline}\n${formatHubHealth(health)}`,
@@ -524,8 +737,192 @@ function withHealth(
   };
 }
 
-/** Applies a create, resume, or adopt plan through the host. Resume does not write. */
-export function applyWorkspacePlan(host: WorkspaceHost, plan: WorkspacePlan, skeletonRoot: string): WorkspaceApplyResult {
+/**
+ * Read-only inventory validation: runs `gh repo view --json name` for each
+ * repository id, batched. Tolerates a missing or failing `gh` by skipping with
+ * a note; marks ids whose check fails as unknown. Never mutates the inventory.
+ */
+export function checkInventoryEntries(host: WorkspaceHost, directory: string): InventoryValidationReport {
+  const raw = host.readText(join(directory, WORKSPACE_INVENTORY_REL));
+  const observation = inspectInventory(raw);
+  if (observation.status !== "populated") {
+    return { entries: [], skipped: true, note: `inventory is ${observation.status}; nothing to validate` };
+  }
+  const available = commandAvailable(host, "gh");
+  if (!available) {
+    return { entries: [], skipped: true, note: "`gh` is unavailable; inventory ids were not validated" };
+  }
+  const ids = readInventoryRepositories(host, join(directory, WORKSPACE_INVENTORY_REL), "the hub inventory").filter(
+    (id) => id !== "",
+  );
+  const batch = 20;
+  const entries: InventoryValidationEntry[] = [];
+  for (let index = 0; index < ids.length; index += batch) {
+    for (const id of ids.slice(index, index + batch)) {
+      const viewed = host.run("gh", ["repo", "view", id, "--json", "name"]);
+      if (viewed.status === 0) {
+        entries.push({ id, known: true });
+      } else if (viewed.status === 127 || (viewed.status === null && viewed.stderr.includes("ENOENT"))) {
+        entries.push({ id, known: null, note: "`gh` unavailable; not checked" });
+      } else {
+        entries.push({ id, known: false, note: "`gh repo view` failed; the repository may not exist" });
+      }
+    }
+  }
+  return { entries, skipped: false };
+}
+
+function shouldRefreshConsumerAgents(existing: string | null): boolean {
+  if (existing === null) return true;
+  if (existing === CONSUMER_AGENTS_MD) return false;
+  if (existing === LEGACY_CONSUMER_AGENTS_MD) return true;
+  if (existing.includes("Run `npx @clossys/launcher` again to resume")) return true;
+  return false;
+}
+
+function writeConsumerAgentsIfNeeded(host: WorkspaceHost, directory: string): void {
+  const existing = host.readText(join(directory, "AGENTS.md"));
+  if (!shouldRefreshConsumerAgents(existing)) return;
+  writeSkeletonFile(host, directory, "AGENTS.md", CONSUMER_AGENTS_MD);
+}
+
+function writeSisterConsumerAgentsIfNeeded(host: WorkspaceHost, directory: string): void {
+  const existing = host.readText(join(directory, "AGENTS.md"));
+  if (existing !== null && existing.trim() !== "" && existing !== SISTER_CONSUMER_AGENTS_MD) return;
+  writeSkeletonFile(host, directory, "AGENTS.md", SISTER_CONSUMER_AGENTS_MD);
+}
+
+const CLONE_NOT_BESIDE_HUB_NOTE =
+  "clone not next to the hub; voices appear here after this repository is cloned beside the hub and launcher resumes";
+
+function parseInventoryRepositoryId(id: string, hubOwner: string): { owner: string; repository: string } | null {
+  const trimmed = id.trim();
+  if (trimmed === "") return null;
+  if (trimmed.includes("/")) {
+    const slash = trimmed.indexOf("/");
+    const owner = trimmed.slice(0, slash);
+    const repository = trimmed.slice(slash + 1);
+    if (!OWNER.test(owner) || !REPO.test(repository)) return null;
+    return { owner, repository };
+  }
+  if (!REPO.test(trimmed)) return null;
+  return { owner: hubOwner, repository: trimmed };
+}
+
+function resolveSisterCloneTargets(
+  host: WorkspaceHost,
+  hubDirectory: string,
+  hubOwner: string,
+): {
+  readonly targets: readonly { readonly inventoryId: string; readonly directory: string }[];
+  readonly skipped: readonly { readonly inventoryId: string; readonly note: string }[];
+} {
+  const parent = dirname(resolve(hubDirectory));
+  const hubResolved = resolve(hubDirectory);
+  const skipped: { inventoryId: string; note: string }[] = [];
+  const targets: { inventoryId: string; directory: string }[] = [];
+  const inventoryPath = join(hubDirectory, WORKSPACE_INVENTORY_REL);
+  let inventoryIds: readonly string[];
+  try {
+    inventoryIds = readInventoryRepositories(host, inventoryPath, "the hub inventory");
+  } catch {
+    return { targets: [], skipped: [] };
+  }
+  for (const id of inventoryIds) {
+    if (id === "") continue;
+    const parsed = parseInventoryRepositoryId(id, hubOwner);
+    if (parsed === null) {
+      skipped.push({ inventoryId: id, note: "inventory id is not a valid repository slug" });
+      continue;
+    }
+    if (parsed.owner !== hubOwner) {
+      skipped.push({ inventoryId: id, note: "other account; not this roster" });
+      continue;
+    }
+    const candidate = join(parent, parsed.repository);
+    const candidateResolved = resolve(candidate);
+    if (candidateResolved === hubResolved) continue;
+    if (!host.exists(candidate) || !host.isDirectory(candidate)) {
+      skipped.push({ inventoryId: id, note: CLONE_NOT_BESIDE_HUB_NOTE });
+      continue;
+    }
+    if (looksLikeFoundry(host, candidate)) {
+      skipped.push({ inventoryId: id, note: "foundry supplier tree; skills are not written here" });
+      continue;
+    }
+    const originResult = host.run("git", ["remote", "get-url", "origin"], { cwd: candidate });
+    const originUrl = originResult.status === 0 ? originResult.stdout.trim() : "";
+    const remote = originUrl === "" ? null : parseGitHubRemote(originUrl);
+    if (remote === null || remote.owner !== parsed.owner || remote.repository !== parsed.repository) {
+      skipped.push({ inventoryId: id, note: "git origin does not match inventory id" });
+      continue;
+    }
+    targets.push({ inventoryId: id, directory: candidate });
+  }
+  return { targets, skipped };
+}
+
+function hubRosterId(host: WorkspaceHost, hubDirectory: string, hubOwner: string, hubRepository: string): string {
+  const document = readHub(host, hubDirectory);
+  if (document !== undefined) return document.repository;
+  return `${hubOwner}/${hubRepository}`;
+}
+
+function composeSkillRoster(
+  host: WorkspaceHost,
+  hubDirectory: string,
+  hubOwner: string,
+  hubRepository: string,
+  options: { launcherPackageRoot: string; skillCatalogueRoot?: string },
+): SkillCompositionResult & {
+  readonly rosterTargets: readonly string[];
+  readonly rosterSkipped: readonly { readonly inventoryId: string; readonly note: string }[];
+} {
+  const hubSkill = composeSkills(host, hubDirectory, {
+    launcherPackageRoot: options.launcherPackageRoot,
+    ...(options.skillCatalogueRoot === undefined ? {} : { skillCatalogueRoot: options.skillCatalogueRoot }),
+  });
+  writeConsumerAgentsIfNeeded(host, hubDirectory);
+  const hubId = hubRosterId(host, hubDirectory, hubOwner, hubRepository);
+  const rosterTargets: string[] = [hubId];
+  const { targets, skipped } = resolveSisterCloneTargets(host, hubDirectory, hubOwner);
+  for (const target of targets) {
+    composeSkills(host, target.directory, {
+      launcherPackageRoot: options.launcherPackageRoot,
+      ...(options.skillCatalogueRoot === undefined ? {} : { skillCatalogueRoot: options.skillCatalogueRoot }),
+    });
+    writeSisterConsumerAgentsIfNeeded(host, target.directory);
+    rosterTargets.push(target.inventoryId);
+  }
+  return { ...hubSkill, rosterTargets, rosterSkipped: skipped };
+}
+
+function finishHubApply(
+  host: WorkspaceHost,
+  directory: string,
+  headline: string,
+  launcherPackageRoot: string,
+  hubOwner: string,
+  hubRepository: string,
+  liveAdvisorVersion?: string,
+  skillCatalogueRoot?: string,
+): WorkspaceApplyResult {
+  const skillComposition = composeSkillRoster(host, directory, hubOwner, hubRepository, {
+    launcherPackageRoot,
+    ...(skillCatalogueRoot === undefined ? {} : { skillCatalogueRoot }),
+  });
+  return withHealth(host, directory, headline, liveAdvisorVersion, skillComposition);
+}
+
+/** Applies a create, resume, or adopt plan through the host. Resume refreshes composed skills and stale AGENTS.md guidance. */
+export function applyWorkspacePlan(
+  host: WorkspaceHost,
+  plan: WorkspacePlan,
+  skeletonRoot: string,
+  options: ApplyWorkspaceOptions = {},
+): WorkspaceApplyResult {
+  const launcherPackageRoot = options.launcherPackageRoot ?? resolve(skeletonRoot, "..");
+  const skillCatalogueRoot = options.skillCatalogueRoot;
   if (plan.action === "resume") {
     if (plan.clone) {
       requireZero(
@@ -533,10 +930,15 @@ export function applyWorkspacePlan(host: WorkspaceHost, plan: WorkspacePlan, ske
         "gh repo clone",
       );
     }
-    return withHealth(
+    return finishHubApply(
       host,
       plan.directory,
       `resumed ${plan.owner}/${plan.repository} as the account hub\nOpen this folder in your coding agent. Advisor stays read-only until you approve a next action.`,
+      launcherPackageRoot,
+      plan.owner,
+      plan.repository,
+      undefined,
+      skillCatalogueRoot,
     );
   }
   if (plan.action === "create") {
@@ -549,22 +951,34 @@ export function applyWorkspacePlan(host: WorkspaceHost, plan: WorkspacePlan, ske
       ),
       "gh repo create",
     );
-    return withHealth(
+    return finishHubApply(
       host,
       plan.directory,
       `created ${plan.owner}/${plan.repository} as the account hub\nOpen this folder in your coding agent. Advisor stays read-only until you approve a next action.`,
+      launcherPackageRoot,
+      plan.owner,
+      plan.repository,
       plan.advisorVersion,
+      skillCatalogueRoot,
     );
   }
   adoptHubFiles(host, skeletonRoot, plan);
-  return withHealth(
+  return finishHubApply(
     host,
     plan.directory,
     `appointed ${plan.owner}/${plan.repository} as the account hub\nExisting project files were kept. This hub inventories engagement; it does not install the catalogue into the repo.`,
+    launcherPackageRoot,
+    plan.owner,
+    plan.repository,
     plan.advisorVersion,
+    skillCatalogueRoot,
   );
 }
 
+export function launcherPackageRootFromModule(moduleUrl: string): string {
+  return resolve(dirname(fileURLToPath(moduleUrl)), "..");
+}
+
 export function skeletonRootFromModule(moduleUrl: string): string {
   return resolve(dirname(fileURLToPath(moduleUrl)), "..", "skeleton");
 }