@clossys/launcher 0.3.0 → 0.4.0

package/src/core.ts

@@ -2,10 +2,14 @@ import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   ApplyWorkspaceOptions,
+  ChosenInventory,
   CommandResult,
   CwdObservation,
   DependencyBucket,
+  EngineInstallFinding,
+  EnginePinChange,
   HubDocument,
+  HubEnginePin,
   HubHealthReport,
   InventoryObservation,
   InventoryValidationEntry,
@@ -16,13 +20,18 @@ import type {
   WorkspaceHost,
   WorkspaceObservation,
   WorkspacePlan,
+  WorkspacePlanAdopt,
   WorkspacePlanCreate,
+  WorkspacePlanResume,
   WorkspaceRefusal,
 } from "./types.js";
 import { composeSkills, SKILLS_MANIFEST_REL, type SkillCompositionResult } from "./skills.js";
 import { parseSkillManifest, summarizeSkillsManifest } from "./manifest.js";
 import { detectLinkedHosts, serializeHostRecord, HOSTS_REL, type DiscoveredHost } from "./hosts.js";
 import { reportInventoryDrift } from "./inventory-adoption.js";
+import { belongsToOwner, distinctOwners, sameOwner, sameRepository } from "./identity.js";
+import { isValidInventoryId, readInventoryDocument, renderInventoryDocument, validateInventoryDocument, type InventoryEntry } from "./inventory-contract.js";
+import { describeChosenInventory, resolveChosenInventory } from "./inventory-choice.js";
 
 export const DEFAULT_REPOSITORY_NAME = "workspace";
 /** The one visible, per-repository Clossys folder (#1171). Every role's output lives under it. */
@@ -37,7 +46,11 @@ export const LEGACY_STATE_DIR_REL = ".clossys";
 export const LEGACY_WORKSPACE_MARKER_REL = join(LEGACY_STATE_DIR_REL, "workspace.json");
 export const LEGACY_WORKSPACE_INVENTORY_REL = join(LEGACY_STATE_DIR_REL, "inventory.json");
 export const ADVISOR_PACKAGE = "@clossys/advisor";
+export const INTEGRATOR_PACKAGE = "@clossys/integrator";
 export const LAUNCHER_PACKAGE = "@clossys/launcher";
+/** The engines a hub pins: each exactly, once, in `devDependencies`, at its live registry version. */
+export const HUB_ENGINE_PACKAGES = [ADVISOR_PACKAGE, INTEGRATOR_PACKAGE] as const;
+type HubEnginePackage = (typeof HUB_ENGINE_PACKAGES)[number];
 
 const DEPENDENCY_BUCKETS: readonly DependencyBucket[] = [
   "dependencies",
@@ -61,6 +74,30 @@ export const CONSUMER_AGENTS_MD = `# Account workspace
 
 This folder is the account hub for Foundry packages.
 
+After \`npx @clossys/launcher\`, the \`@clossys-*\` team is composed in this
+hub. Talk with \`@clossys-advisor\` and \`@clossys-<package>\` here. A launcher
+run writes nothing into a product repository; once a repository is staffed
+in an approved plan, it gets \`@clossys-advisor\` and the voices of the roles
+staffed there, with that plan's setup pull request. A missing \`@\` mention
+is a bug only here in the hub; in a product repository, a role that is not
+staffed there is expected to be absent. \`@clossys-advisor\` is the hiring
+check.
+
+Run \`npx @clossys/launcher\` again for hub health and to refresh the voices
+in this hub, not as how you talk to packages.
+
+The person in this folder is a founder, not an engineer. Speak like a
+person. Do not dump machine identifiers, JSON, hashes, or grant fields
+unless they ask.
+
+Advisor is read-only until the sponsor approves a next action.
+`;
+
+/** The hub guidance written while a launcher run still composed the team into checkouts beside the hub; resume refreshes it. */
+export const SIBLING_COMPOSING_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
@@ -76,15 +113,6 @@ unless they ask.
 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
 
@@ -195,7 +223,7 @@ export function isHubDocument(value: unknown): value is HubDocument {
   const parsed = value.repository.includes("/")
     ? { owner: value.repository.split("/")[0], repository: value.repository.split("/")[1] }
     : null;
-  if (!parsed?.owner || !parsed.repository || parsed.owner !== value.owner || !REPO.test(parsed.repository)) return false;
+  if (!parsed?.owner || !parsed.repository || !sameOwner(parsed.owner, value.owner) || !REPO.test(parsed.repository)) return false;
   return true;
 }
 
@@ -215,8 +243,9 @@ function readHubAt(host: WorkspaceHost, path: string): HubDocument | undefined {
  * migration (#1171). `clean`: only the current path has a marker. `legacy`:
  * only the old path does; resume migrates it (see `migrateLegacyHubState`).
  * `indeterminate`: both paths carry a parseable marker; launcher never
- * merges them silently, so `planWorkspace` refuses instead. `none`: neither
- * path has one.
+ * merges them silently, so `planWorkspace` refuses instead (and, for a hub
+ * cloned from an empty directory, `classifyClonedHub` at apply time).
+ * `none`: neither path has one.
  */
 function locateHub(
   host: WorkspaceHost,
@@ -234,19 +263,26 @@ function readHub(host: WorkspaceHost, directory: string): HubDocument | undefine
   return locateHub(host, directory).document;
 }
 
-/** Classifies a generated hub inventory (packed template skeleton/clossys/.state/inventory.json; the generated path does not ship) without inventing repositories. */
-export function inspectInventory(raw: string | null): InventoryObservation {
+/**
+ * The inventory document's shape lives in docs/contracts/repository-inventory.json
+ * (in the public repository; that exact path does not ship in this
+ * package, but this package's build packs and ships its own copy of the
+ * contract) and is checked, on every read and write, by
+ * `validateInventoryDocument()` through the shared contract checker
+ * (./inventory-contract.ts, #1334, #1179).
+ */
+export { validateInventoryDocument } from "./inventory-contract.js";
+export type { InventoryValidation } from "./inventory-contract.js";
+
+/**
+ * Classifies a generated hub inventory (packed template skeleton/clossys/.state/inventory.json; the generated path does not ship) without inventing repositories. Malformed input is "invalid", never silently folded into "empty" (#1334).
+ * Pass the file's exact bytes (`WorkspaceHost.readBytes()`), and the hub's owner when it is known, so a bare id and `<owner>/<id>` count as one repository (#1179).
+ */
+export function inspectInventory(raw: string | Uint8Array | null, hubOwner?: string): InventoryObservation {
   if (raw === null) return { status: "missing", count: 0 };
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    if (!isRecord(parsed) || parsed.schemaVersion !== 1 || !Array.isArray(parsed.repositories)) {
-      return { status: "empty", count: 0 };
-    }
-    const count = parsed.repositories.length;
-    return { status: count > 0 ? "populated" : "empty", count };
-  } catch {
-    return { status: "empty", count: 0 };
-  }
+  const validated = validateInventoryDocument(raw, hubOwner === undefined ? {} : { hubOwner });
+  if (!validated.valid) return { status: "invalid", count: 0, reason: validated.reason };
+  return { status: validated.ids.length > 0 ? "populated" : "empty", count: validated.ids.length };
 }
 
 function looksLikeFoundry(host: WorkspaceHost, directory: string): boolean {
@@ -284,21 +320,37 @@ function commandAvailable(host: WorkspaceHost, command: string): boolean {
 /** 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);
+  return DEPENDENCY_BUCKETS.some((bucket) => enginePinsIn(manifest[bucket], new Set())[ADVISOR_PACKAGE] !== undefined);
+}
+
+/**
+ * The one place Launcher learns a package's live version: the public npm
+ * registry (`npm view <name> version`). A failed or unparseable read is
+ * `undefined`, never a guess.
+ */
+function readRegistryVersion(host: WorkspaceHost, name: string): string | undefined {
+  const viewed = host.run("npm", ["view", name, "version"]);
+  const version = viewed.stdout.trim();
+  return viewed.status === 0 && /^\d+\.\d+\.\d+$/.test(version) ? version : undefined;
 }
 
-/** Collects GitHub owner, cwd shape, default-hub presence, and the public Advisor pin. */
 /**
  * Reads the public `@clossys/launcher` registry version, used only to grade
  * catalogue-sourced skill staleness in the health report (#1183). A missing
  * or unparseable read leaves staleness ungraded rather than refusing.
  */
 export function readLiveLauncherVersion(host: WorkspaceHost): string | undefined {
-  const viewed = host.run("npm", ["view", LAUNCHER_PACKAGE, "version"]);
-  const version = viewed.stdout.trim();
-  return viewed.status === 0 && /^\d+\.\d+\.\d+$/.test(version) ? version : undefined;
+  return readRegistryVersion(host, LAUNCHER_PACKAGE);
 }
 
+/**
+ * Collects GitHub owner, cwd shape, default-hub presence, and the public
+ * Advisor and Integrator versions. Default-hub presence means only that
+ * `{owner}/workspace` exists on GitHub; its contents (marker, legacy marker,
+ * or none) are not observed here but classified after the clone, at apply
+ * time (#1585).
+ */
+
 export function observeWorkspace(host: WorkspaceHost): WorkspaceObservation {
   const cwd = host.cwd;
   const ghAvailable = commandAvailable(host, "gh");
@@ -315,37 +367,38 @@ export function observeWorkspace(host: WorkspaceHost): WorkspaceObservation {
       githubRepository = parsed.repository;
     }
   }
-  const candidates = new Set<string>();
+  // Owners are compared as GitHub compares them (identity.ts): two spellings of one account are one candidate.
+  const seenOwners: string[] = [];
   const envOwnerRaw = host.env.CLOSSYS_OWNER?.trim();
   const envOwner = envOwnerRaw && OWNER.test(envOwnerRaw) ? envOwnerRaw : undefined;
   if (ghAvailable) {
     const user = host.run("gh", ["api", "user", "--jq", ".login"]);
     const login = user.stdout.trim();
-    if (user.status === 0 && OWNER.test(login)) candidates.add(login);
+    if (user.status === 0 && OWNER.test(login)) seenOwners.push(login);
     for (const org of stdoutLines(host.run("gh", ["org", "list"]))) {
-      if (OWNER.test(org)) candidates.add(org);
+      if (OWNER.test(org)) seenOwners.push(org);
     }
   }
-  if (githubOwner) candidates.add(githubOwner);
+  if (githubOwner) seenOwners.push(githubOwner);
+  const candidates = new Set(distinctOwners(seenOwners));
 
   let remoteDefaultHub: WorkspaceObservation["remoteDefaultHub"];
-  let advisorVersion: string | undefined;
   const ownerGuess = envOwner ?? (candidates.size === 1 ? [...candidates][0] : githubOwner);
   if (ghAvailable && ownerGuess) {
     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;
+  const advisorVersion = readRegistryVersion(host, ADVISOR_PACKAGE);
+  const integratorVersion = readRegistryVersion(host, INTEGRATOR_PACKAGE);
 
   const hubLocation = locateHub(host, cwd);
   // While only the legacy `.clossys/` marker exists, its sibling inventory is
   // the one resume will migrate; read from there so planning sees it too.
-  const inventoryRaw =
+  const inventoryBytes =
     hubLocation.migration === "legacy"
-      ? host.readText(join(cwd, LEGACY_WORKSPACE_INVENTORY_REL))
-      : host.readText(join(cwd, WORKSPACE_INVENTORY_REL));
+      ? host.readBytes(join(cwd, LEGACY_WORKSPACE_INVENTORY_REL))
+      : host.readBytes(join(cwd, WORKSPACE_INVENTORY_REL));
+  const inventoryOwner = hubLocation.document?.owner ?? githubOwner;
 
   const cwdObservation: CwdObservation = {
     absolutePath: cwd,
@@ -356,7 +409,7 @@ export function observeWorkspace(host: WorkspaceHost): WorkspaceObservation {
     ...(hubLocation.document === undefined ? {} : { hub: hubLocation.document }),
     ...(hubLocation.migration === "none" ? {} : { hubMigration: hubLocation.migration }),
     looksLikeFoundry: looksLikeFoundry(host, cwd),
-    inventory: inspectInventory(inventoryRaw),
+    inventory: inspectInventory(inventoryBytes, inventoryOwner),
   };
 
   return {
@@ -365,6 +418,7 @@ export function observeWorkspace(host: WorkspaceHost): WorkspaceObservation {
     ...(envOwner === undefined ? {} : { envOwner }),
     ...(remoteDefaultHub === undefined ? {} : { remoteDefaultHub }),
     ...(advisorVersion === undefined ? {} : { advisorVersion }),
+    ...(integratorVersion === undefined ? {} : { integratorVersion }),
     ghAvailable,
     gitAvailable,
   };
@@ -393,19 +447,38 @@ 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);
+/**
+ * Reads repository ids from a `schemaVersion: 1` inventory document, routed
+ * through `validateInventoryDocument` -- the same schema check `--inventory`
+ * and `inspectInventory` apply, so a caller here can never end up trusting a
+ * document neither of those would have accepted (#1334). Throws, naming the
+ * offending field, on anything present but invalid; a missing file is `[]`,
+ * not a throw -- an absent inventory is a fact about the hub, not a
+ * malformed one. The file is read as bytes; `hubOwner`, when given, makes a
+ * bare id and `<hubOwner>/<id>` one repository, so a document listing both
+ * is refused.
+ */
+export function readInventoryRepositories(host: WorkspaceHost, source: string, label: string, hubOwner?: string): readonly string[] {
+  const raw = host.readBytes(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)`);
-  }
+  const validated = validateInventoryDocument(raw, hubOwner === undefined ? {} : { hubOwner });
+  if (!validated.valid) throw new Error(`${label} ${validated.reason}`);
+  return validated.ids;
+}
+
+/**
+ * How a founder gives Launcher the repositories a hub covers (#1179): they
+ * choose them on Advisor's repository-choice card, and `--repositories`
+ * writes the inventory. Named by every refusal that needs an inventory,
+ * instead of `--inventory <path>`, which still works but asks for a
+ * document a founder will not write.
+ */
+function chooseRepositoriesHint(extraFlag = ""): string {
+  return (
+    "choose the repositories this hub covers on Advisor's repository card " +
+    "(`npx -p @clossys/advisor advisor-repository-card`), built from the repositories GitHub lists for your sign-in, then run " +
+    `\`launcher --repositories <owner/name>[,<owner/name>...]${extraFlag}\`, and Launcher writes the inventory for you`
+  );
 }
 
 /**
@@ -420,48 +493,135 @@ function resolveAdoptInventory(
   host: WorkspaceHost,
   cwd: CwdObservation,
   inventoryPath: string | undefined,
-): { inventorySource?: string; mergedInventoryIds?: readonly string[] } | WorkspaceRefusal {
+):
+  | {
+      inventorySource?: string;
+      mergedInventoryIds?: readonly string[];
+      mergedInventoryRepositories?: readonly InventoryEntry[];
+      mergedInventoryDocument?: string;
+      replacesInvalidInventory?: boolean;
+    }
+  | WorkspaceRefusal {
   const trimmed = inventoryPath?.trim();
   const onDiskPopulated = cwd.inventory?.status === "populated";
   if (!onDiskPopulated && !trimmed) {
+    if (cwd.inventory?.status === "invalid") {
+      return refuse(
+        "violated",
+        `the on-disk hub inventory ${cwd.inventory.reason ?? "does not conform to the inventory contract"} -- to replace it, ${chooseRepositoriesHint(" --replace-inventory")}`,
+      );
+    }
     return refuse(
       "violated",
-      "appointing requires a populated generated hub inventory (packed template skeleton/clossys/.state/inventory.json; the generated path does not ship), or --inventory <path> to a populated inventory document",
+      `appointing needs the repositories this hub covers, and it has no inventory yet: ${chooseRepositoriesHint()}`,
     );
   }
   if (!trimmed) return {};
   const resolved = resolve(cwd.absolutePath, trimmed);
-  const imported = inspectInventory(host.readText(resolved));
-  if (imported.status !== "populated") {
+  const importedRaw = host.readBytes(resolved);
+  if (importedRaw === null) {
+    return refuse("violated", `--inventory does not point at a readable file: ${resolved}`);
+  }
+  const owner = cwd.githubOwner === undefined ? {} : { hubOwner: cwd.githubOwner };
+  const imported = readInventoryDocument(importedRaw, owner);
+  if (!imported.valid) {
+    return refuse("violated", `--inventory at ${resolved} ${imported.reason}`);
+  }
+  if (imported.ids.length === 0) {
     return refuse(
       "violated",
-      "--inventory must point at a populated inventory document (schemaVersion 1, nonempty repositories)",
+      `--inventory at ${resolved} must be a populated inventory document (nonempty repositories)`,
     );
   }
-  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);
-    }
+  if (!onDiskPopulated) {
+    return {
+      inventorySource: resolved,
+      ...(cwd.inventory?.status === "invalid" ? { replacesInvalidInventory: true } : {}),
+    };
   }
-  for (const id of readInventoryRepositories(host, resolved, "--inventory")) {
-    if (id !== "" && !seen.has(id)) {
-      seen.add(id);
-      merged.push(id);
-    }
+  const onDiskRaw = host.readBytes(join(cwd.absolutePath, WORKSPACE_INVENTORY_REL));
+  const onDisk = onDiskRaw === null ? undefined : readInventoryDocument(onDiskRaw, owner);
+  if (onDisk !== undefined && !onDisk.valid) {
+    return refuse("violated", `the on-disk hub inventory ${onDisk.reason}`);
   }
-  return { mergedInventoryIds: merged };
+  const onDiskEntries: readonly InventoryEntry[] = onDisk !== undefined && onDisk.valid ? onDisk.entries : [];
+  // Merge whole entries, not ids: an entry's `packages` travels with it.
+  // Entries are keyed by Launcher's one repository identity (identity.ts),
+  // the same rule validateInventoryDocument() applies to ids, so the merge
+  // can never write a document the validator then refuses; the first
+  // occurrence -- the on-disk spelling and entry -- wins (#1334, #1179).
+  const merged: InventoryEntry[] = [];
+  for (const entry of [...onDiskEntries, ...imported.entries]) {
+    if (!merged.some((kept) => sameRepository(kept.id, entry.id, cwd.githubOwner))) merged.push(entry);
+  }
+  return {
+    mergedInventoryIds: merged.map((entry) => entry.id),
+    mergedInventoryRepositories: merged,
+    mergedInventoryDocument: renderInventoryDocument(merged),
+  };
+}
+
+/**
+ * Resolves `--repositories` against the inventory stored in `directory`, or
+ * returns a refusal. See `resolveChosenInventory()`.
+ */
+function resolveChosenRepositories(
+  host: WorkspaceHost,
+  directory: string,
+  owner: string,
+  repositories: readonly string[],
+  replaceInventory: boolean,
+): { chosenInventory: ChosenInventory } | WorkspaceRefusal {
+  const resolution = resolveChosenInventory(host.readBytes(join(directory, WORKSPACE_INVENTORY_REL)), repositories, owner, replaceInventory);
+  if (resolution.kind === "refuse") return refuse("violated", resolution.message);
+  return { chosenInventory: resolution.chosen };
+}
+
+export interface PlanWorkspaceOptions {
+  /** `--inventory <path>`: a prepared inventory document, appoint only. */
+  readonly inventoryPath?: string;
+  /** `--repositories`: the repository ids a founder chose on Advisor's repository card (#1179). Appoint or resume of a hub checkout. */
+  readonly repositories?: readonly string[];
+  /** `--replace-inventory`: explicit approval for `repositories` to replace a stored inventory that lists a different set, or one that fails its contract. */
+  readonly replaceInventory?: boolean;
+}
+
+/** The hub engine versions a plan carries, only those the observation read. */
+function observedEngineVersions(observation: WorkspaceObservation): { advisorVersion?: string; integratorVersion?: string } {
+  return {
+    ...(observation.advisorVersion === undefined ? {} : { advisorVersion: observation.advisorVersion }),
+    ...(observation.integratorVersion === undefined ? {} : { integratorVersion: observation.integratorVersion }),
+  };
+}
+
+/**
+ * Create and appoint pin both hub engines, so each needs its live version:
+ * the refusal names the first one the registry did not answer for.
+ */
+function requireEngineVersions(
+  observation: WorkspaceObservation,
+): { advisorVersion: string; integratorVersion: string } | WorkspaceRefusal {
+  if (!observation.advisorVersion) {
+    return refuse("indeterminate", `cannot read a public ${ADVISOR_PACKAGE} version from the npm registry`);
+  }
+  if (!observation.integratorVersion) {
+    return refuse("indeterminate", `cannot read a public ${INTEGRATOR_PACKAGE} version from the npm registry`);
+  }
+  return { advisorVersion: observation.advisorVersion, integratorVersion: observation.integratorVersion };
 }
 
 export function planWorkspace(
   observation: WorkspaceObservation,
   host: WorkspaceHost,
-  options: { inventoryPath?: string } = {},
+  options: PlanWorkspaceOptions = {},
 ): WorkspaceDecision {
   const { cwd } = observation;
+  if (options.repositories !== undefined && options.inventoryPath !== undefined) {
+    return refuse("violated", "--repositories and --inventory each supply the whole inventory; use one, not both");
+  }
+  if (options.replaceInventory === true && options.repositories === undefined) {
+    return refuse("violated", "--replace-inventory approves replacing the inventory with --repositories, and means nothing without it");
+  }
   if (cwd.hubMigration === "indeterminate") {
     return refuse(
       "indeterminate",
@@ -475,7 +635,7 @@ export function planWorkspace(
     cwd.hub === undefined &&
     cwd.git &&
     cwd.githubOwner !== undefined &&
-    cwd.githubOwner !== envOwner
+    !sameOwner(cwd.githubOwner, envOwner)
   ) {
     return refuse(
       "violated",
@@ -489,19 +649,43 @@ export function planWorkspace(
     );
   }
   if (cwd.hub) {
+    let chosen: { chosenInventory: ChosenInventory } | undefined;
+    if (options.repositories !== undefined) {
+      if (cwd.hubMigration === "legacy") {
+        return refuse(
+          "violated",
+          "this hub's state is still in the legacy .clossys/ folder; run launcher once without --repositories to move it to clossys/.state/, then choose the repositories again",
+        );
+      }
+      const resolved = resolveChosenRepositories(host, cwd.absolutePath, cwd.hub.owner, options.repositories, options.replaceInventory === true);
+      if ("action" in resolved) return resolved;
+      chosen = resolved;
+    }
     return {
       action: "resume",
       owner: cwd.hub.owner,
       repository: repoNameFromSlug(cwd.hub.repository, DEFAULT_REPOSITORY_NAME),
       directory: cwd.absolutePath,
       clone: false,
-      ...(observation.advisorVersion === undefined ? {} : { advisorVersion: observation.advisorVersion }),
+      ...observedEngineVersions(observation),
       ...(cwd.hubMigration === "legacy" ? { migrateFrom: "legacy" as const } : {}),
+      ...(chosen ?? {}),
     };
   }
   if (cwd.git && cwd.githubOwner && cwd.githubRepository) {
-    if (!observation.advisorVersion) {
-      return refuse("indeterminate", `cannot read a public ${ADVISOR_PACKAGE} version from the npm registry`);
+    const engines = requireEngineVersions(observation);
+    if ("action" in engines) return engines;
+    if (options.repositories !== undefined) {
+      const resolved = resolveChosenRepositories(host, cwd.absolutePath, cwd.githubOwner, options.repositories, options.replaceInventory === true);
+      if ("action" in resolved) return resolved;
+      return {
+        action: "adopt",
+        owner: cwd.githubOwner,
+        repository: cwd.githubRepository,
+        directory: cwd.absolutePath,
+        ...engines,
+        chosenInventory: resolved.chosenInventory,
+      };
     }
     const imported = resolveAdoptInventory(host, cwd, options.inventoryPath);
     if ("action" in imported) return imported;
@@ -510,9 +694,12 @@ export function planWorkspace(
       owner: cwd.githubOwner,
       repository: cwd.githubRepository,
       directory: cwd.absolutePath,
-      advisorVersion: observation.advisorVersion,
+      ...engines,
       ...(imported.inventorySource === undefined ? {} : { inventorySource: imported.inventorySource }),
       ...(imported.mergedInventoryIds === undefined ? {} : { mergedInventoryIds: imported.mergedInventoryIds }),
+      ...(imported.mergedInventoryRepositories === undefined ? {} : { mergedInventoryRepositories: imported.mergedInventoryRepositories }),
+      ...(imported.mergedInventoryDocument === undefined ? {} : { mergedInventoryDocument: imported.mergedInventoryDocument }),
+      ...(imported.replacesInvalidInventory === undefined ? {} : { replacesInvalidInventory: imported.replacesInvalidInventory }),
     };
   }
   if (cwd.git) {
@@ -524,30 +711,38 @@ export function planWorkspace(
       "the current directory is not empty and is not a GitHub repository; run from the repo you want to appoint, or from an empty directory",
     );
   }
+  if (options.repositories !== undefined) {
+    return refuse(
+      "violated",
+      "--repositories writes the inventory of a hub checkout, and this directory is empty; run launcher here first to create or clone the hub, then choose its repositories from inside it",
+    );
+  }
   const ownerResult = resolveOwner(observation, host);
   if ("action" in ownerResult) return ownerResult;
-  if (observation.remoteDefaultHub && observation.remoteDefaultHub.owner === ownerResult.owner) {
+  if (observation.remoteDefaultHub && sameOwner(observation.remoteDefaultHub.owner, ownerResult.owner)) {
+    // A clone plan: whether `{owner}/workspace` is already a hub (marked, legacy-marked) or an existing
+    // repository to appoint (unmarked) is not known until it is cloned, so applyWorkspacePlan classifies
+    // it then (classifyClonedHub, #1585) and may take the adopt path instead of resuming.
     return {
       action: "resume",
       owner: observation.remoteDefaultHub.owner,
       repository: observation.remoteDefaultHub.repository,
       directory: cwd.absolutePath,
       clone: true,
-      ...(observation.advisorVersion === undefined ? {} : { advisorVersion: observation.advisorVersion }),
+      ...observedEngineVersions(observation),
     };
   }
   if (!observation.ghAvailable) {
     return refuse("indeterminate", "`gh` is required to create a GitHub repository for a new hub");
   }
-  if (!observation.advisorVersion) {
-    return refuse("indeterminate", `cannot read a public ${ADVISOR_PACKAGE} version from the npm registry`);
-  }
+  const engines = requireEngineVersions(observation);
+  if ("action" in engines) return engines;
   return {
     action: "create",
     owner: ownerResult.owner,
     repository: DEFAULT_REPOSITORY_NAME,
     directory: cwd.absolutePath,
-    advisorVersion: observation.advisorVersion,
+    ...engines,
   };
 }
 
@@ -560,11 +755,15 @@ function containedPath(root: string, relativePath: string): string {
   return resolved;
 }
 
-function substitute(contents: string, plan: { owner: string; repository: string; advisorVersion?: string }): string {
+function substitute(
+  contents: string,
+  plan: { owner: string; repository: string; advisorVersion?: string; integratorVersion?: string },
+): string {
   return contents
     .replaceAll("__OWNER__", plan.owner)
     .replaceAll("__REPOSITORY_NAME__", plan.repository)
-    .replaceAll("__ADVISOR_VERSION__", plan.advisorVersion ?? "0.0.0");
+    .replaceAll("__ADVISOR_VERSION__", plan.advisorVersion ?? "0.0.0")
+    .replaceAll("__INTEGRATOR_VERSION__", plan.integratorVersion ?? "0.0.0");
 }
 
 function writeSkeletonFile(host: WorkspaceHost, directory: string, relativePath: string, contents: string): void {
@@ -573,69 +772,242 @@ function writeSkeletonFile(host: WorkspaceHost, directory: string, relativePath:
   host.writeText(target, contents);
 }
 
+/** Writes exact bytes, for a document copied rather than composed, so nothing is decoded and re-encoded on the way. */
+function writeSkeletonBytes(host: WorkspaceHost, directory: string, relativePath: string, contents: Uint8Array): void {
+  const target = containedPath(directory, relativePath);
+  host.mkdirp(dirname(target));
+  host.writeBytes(target, contents);
+}
+
+function withFinalNewline(bytes: Uint8Array): Uint8Array {
+  if (bytes.length > 0 && bytes[bytes.length - 1] === 0x0a) return bytes;
+  const out = new Uint8Array(bytes.length + 1);
+  out.set(bytes);
+  out[bytes.length] = 0x0a;
+  return out;
+}
+
 function pinString(value: unknown): string | undefined {
   return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
 }
 
-function clossysNames(bucket: unknown, extra: Set<string>): string | undefined {
-  if (!isRecord(bucket)) return undefined;
-  let advisor: string | undefined;
+/**
+ * The hub engine pins in one dependency bucket, by engine. Every other
+ * `@clossys/*` name found there is added to `extra`.
+ */
+function enginePinsIn(bucket: unknown, extra: Set<string>): Partial<Record<HubEnginePackage, string>> {
+  const pins: Partial<Record<HubEnginePackage, string>> = {};
+  if (!isRecord(bucket)) return pins;
   for (const [name, version] of Object.entries(bucket)) {
-    if (name === ADVISOR_PACKAGE) {
-      advisor = pinString(version);
+    const engine = HUB_ENGINE_PACKAGES.find((candidate) => candidate === name);
+    if (engine !== undefined) {
+      const pinned = pinString(version);
+      if (pinned !== undefined) pins[engine] = pinned;
       continue;
     }
     if (name.startsWith("@clossys/")) extra.add(name);
   }
-  return advisor;
+  return pins;
+}
+
+/** The live engine versions to pin; an engine whose version is unknown is left as the manifest has it. */
+interface HubEngineVersions {
+  readonly advisorVersion?: string;
+  readonly integratorVersion?: string;
+}
+
+function engineVersionEntries(versions: HubEngineVersions): readonly (readonly [HubEnginePackage, string])[] {
+  const entries: (readonly [HubEnginePackage, string])[] = [];
+  if (versions.advisorVersion !== undefined) entries.push([ADVISOR_PACKAGE, versions.advisorVersion]);
+  if (versions.integratorVersion !== undefined) entries.push([INTEGRATOR_PACKAGE, versions.integratorVersion]);
+  return entries;
+}
+
+/** A `package.json` body parsed to a JSON object, or `undefined` when it is unparseable, an array, or a primitive. */
+function parseManifestObject(raw: string): Record<string, unknown> | undefined {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The manifest refusals of `mergeHubEnginePins` in "appoint" mode, raised by
+ * `adoptHubFiles` before its first write so a refusal leaves the checkout
+ * untouched: a `package.json` that is a symbolic link (live or dangling, never
+ * resolved, so the write cannot land outside the checkout), a present one that
+ * is unreadable or not a JSON object, or a missing one with no skeleton
+ * manifest to write in its place.
+ */
+function assertManifestAppointable(host: WorkspaceHost, directory: string, skeletonRoot: string): void {
+  const manifestPath = join(directory, "package.json");
+  if (host.isSymlink(manifestPath)) {
+    throw new Error("existing package.json is a symbolic link; replace it with a regular file before appointing");
+  }
+  const raw = host.readText(manifestPath);
+  if (raw === null) {
+    // readText collapses every read error to null, so tell "absent" from
+    // "present but unreadable" (a directory, no read permission).
+    if (host.exists(manifestPath)) {
+      throw new Error("existing package.json is present but cannot be read (is it a directory, or unreadable?)");
+    }
+    if (host.readText(join(skeletonRoot, "package.json")) === null) throw new Error("missing skeleton package.json");
+    return;
+  }
+  if (parseManifestObject(raw) === undefined) throw new Error("existing package.json is unreadable JSON");
 }
 
 /**
- * Pins live Advisor in `devDependencies` only. Relocates a pin left in any
- * other bucket and overwrites a frozen version. Does not touch other
- * `@clossys/*` names. A dedicated `{owner}/workspace` hub is named
- * `@owner/workspace`.
+ * Pins each hub engine (Advisor and Integrator) exactly, in `devDependencies`
+ * only, and returns what it changed. It only raises a pin: one older than
+ * live, or not a plain version (a range, a tag), becomes the live version;
+ * one newer than live is kept as it is. A pin left in any other bucket is
+ * moved to `devDependencies`. Other `@clossys/*` names are not touched. The
+ * manifest is written as 2-space-indented JSON with a final LF.
+ *
+ * `appoint` writes the packed skeleton manifest when the hub has none,
+ * refuses a manifest that is not a JSON object, names a dedicated
+ * `{owner}/workspace` hub `@owner/workspace` only when its manifest has no
+ * own `name` (an existing name is never overwritten, #1585), and rewrites
+ * the manifest.
+ * `resume` changes only the engine pins (never the `name`), writes the
+ * manifest only when a pin changed, and leaves a missing or unreadable
+ * manifest as it is (the health report then shows the engine pins as
+ * missing).
  */
-function mergeAdvisorPin(
+function mergeHubEnginePins(
   host: WorkspaceHost,
   directory: string,
   skeletonRoot: string,
-  advisorVersion: string,
+  versions: HubEngineVersions,
   owner: string,
   repository: string,
-): void {
+  mode: "appoint" | "resume",
+): readonly EnginePinChange[] {
   const path = join(directory, "package.json");
   const raw = host.readText(path);
   if (raw === null) {
+    if (mode === "resume") return [];
     const skeleton = host.readText(join(skeletonRoot, "package.json"));
     if (skeleton === null) throw new Error("missing skeleton package.json");
-    writeSkeletonFile(host, directory, "package.json", substitute(skeleton, { owner, repository, advisorVersion }));
-    return;
+    writeSkeletonFile(host, directory, "package.json", substitute(skeleton, { owner, repository, ...versions }));
+    return engineVersionEntries(versions).map(([engine, version]) => ({ package: engine, to: version }));
   }
-  let manifest: Record<string, unknown>;
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    if (!isRecord(parsed)) throw new Error("package.json is not an object");
-    manifest = parsed;
-  } catch {
+  const manifest = parseManifestObject(raw);
+  if (manifest === undefined) {
+    if (mode === "resume") return [];
     throw new Error("existing package.json is unreadable JSON");
   }
-  for (const bucket of DEPENDENCY_BUCKETS) {
-    if (bucket === "devDependencies") continue;
-    const current = manifest[bucket];
-    if (!isRecord(current) || !(ADVISOR_PACKAGE in current)) continue;
-    const next = { ...current };
-    delete next[ADVISOR_PACKAGE];
-    if (Object.keys(next).length === 0) delete manifest[bucket];
-    else manifest[bucket] = next;
-  }
-  const devDependencies = isRecord(manifest.devDependencies) ? { ...manifest.devDependencies } : {};
-  devDependencies[ADVISOR_PACKAGE] = advisorVersion;
-  manifest.devDependencies = devDependencies;
-  if (repository === DEFAULT_REPOSITORY_NAME) {
+  const changes: EnginePinChange[] = [];
+  for (const [engine, live] of engineVersionEntries(versions)) {
+    const devPin = isRecord(manifest.devDependencies) ? pinString(manifest.devDependencies[engine]) : undefined;
+    let movedFrom: DependencyBucket | undefined;
+    let movedPin: string | undefined;
+    for (const bucket of DEPENDENCY_BUCKETS) {
+      if (bucket === "devDependencies") continue;
+      const current = manifest[bucket];
+      if (!isRecord(current) || !(engine in current)) continue;
+      if (movedFrom === undefined) {
+        movedFrom = bucket;
+        movedPin = pinString(current[engine]);
+      }
+      const next = { ...current };
+      delete next[engine];
+      if (Object.keys(next).length === 0) delete manifest[bucket];
+      else manifest[bucket] = next;
+    }
+    const existing = devPin ?? movedPin;
+    // Only raise: a pin newer than live stays, as the health grader treats it as current.
+    const to = existing !== undefined && compareVersions(existing, live) === 1 ? existing : live;
+    const devDependencies = isRecord(manifest.devDependencies) ? { ...manifest.devDependencies } : {};
+    devDependencies[engine] = to;
+    manifest.devDependencies = devDependencies;
+    if (to !== devPin || movedFrom !== undefined) {
+      changes.push({
+        package: engine,
+        ...(existing === undefined ? {} : { from: existing }),
+        to,
+        ...(devPin === undefined && movedFrom !== undefined ? { movedFrom } : {}),
+      });
+    }
+  }
+  // Only a nameless manifest is named: an existing `name` is the project's own and is never overwritten (#1585).
+  if (mode === "appoint" && repository === DEFAULT_REPOSITORY_NAME && !Object.hasOwn(manifest, "name")) {
     manifest.name = `@${owner}/${repository}`;
   }
+  if (mode === "resume" && changes.length === 0) return changes;
   host.writeText(path, `${JSON.stringify(manifest, null, 2)}\n`);
+  return changes;
+}
+
+/** Lockfiles Launcher recognises in a hub, with the install command that updates each. */
+const HUB_LOCKFILES: readonly (readonly [string, string])[] = [
+  // npm reads npm-shrinkwrap.json instead of package-lock.json when both exist.
+  ["npm-shrinkwrap.json", "npm install"],
+  ["package-lock.json", "npm install"],
+  ["pnpm-lock.yaml", "pnpm install"],
+  ["yarn.lock", "yarn install"],
+  ["bun.lock", "bun install"],
+  ["bun.lockb", "bun install"],
+];
+
+function describeEnginePinChange(change: EnginePinChange): string {
+  const moved = change.movedFrom === undefined ? "" : ` (moved from ${change.movedFrom} to devDependencies)`;
+  if (change.from === undefined) return `${change.package} added at ${change.to}${moved}`;
+  if (change.from === change.to) return `${change.package} ${change.to}${moved}`;
+  return `${change.package} ${change.from} -> ${change.to}${moved}`;
+}
+
+/** The one next step after a run changed engine pins: install with the hub's package manager, then commit the manifest with its lockfile. */
+function enginePinNextStep(host: WorkspaceHost, directory: string): string {
+  const lockfile = HUB_LOCKFILES.find(([name]) => host.exists(join(directory, name)));
+  return lockfile === undefined
+    ? "run your package manager's install in the hub, then commit package.json together with the lockfile it writes"
+    : `run \`${lockfile[1]}\` in the hub, then commit package.json together with ${lockfile[0]}`;
+}
+
+/**
+ * Whether the hub's lockfile resolves its engine pins. An npm lockfile is
+ * read: each engine pinned to a plain version in `devDependencies` must
+ * resolve to that version. Any other lockfile is not read, so it counts as
+ * not resolving the engines this run changed. No lockfile, no finding.
+ */
+function engineInstallFinding(
+  host: WorkspaceHost,
+  directory: string,
+  changes: readonly EnginePinChange[],
+): EngineInstallFinding | undefined {
+  const found = HUB_LOCKFILES.find(([name]) => host.exists(join(directory, name)));
+  if (found === undefined) return undefined;
+  const [lockfile, command] = found;
+  const changed = [...new Set(changes.map((change) => change.package))];
+  let packages: readonly string[] = changed;
+  if (lockfile === "package-lock.json" || lockfile === "npm-shrinkwrap.json") {
+    const lock = readJson(host, join(directory, lockfile));
+    const manifest = readJson(host, join(directory, "package.json"));
+    const devDependencies = isRecord(manifest) && isRecord(manifest.devDependencies) ? manifest.devDependencies : {};
+    if (isRecord(lock)) {
+      packages = HUB_ENGINE_PACKAGES.filter((engine) => {
+        const pinned = pinString(devDependencies[engine]);
+        if (pinned === undefined || compareVersions(pinned, pinned) === null) return false;
+        const lockPackages = isRecord(lock.packages) ? lock.packages : {};
+        const lockDependencies = isRecord(lock.dependencies) ? lock.dependencies : {};
+        const entry = lockPackages[`node_modules/${engine}`] ?? lockDependencies[engine];
+        const locked = isRecord(entry) ? pinString(entry.version) : undefined;
+        return locked === undefined || compareVersions(locked, pinned) !== 0;
+      });
+    }
+  }
+  if (packages.length === 0) return undefined;
+  return {
+    kind: "engine-pins-changed-install-needed",
+    lockfile,
+    command,
+    packages,
+    note: `${lockfile} does not resolve the pinned ${packages.join(" and ")} yet; run \`${command}\` in the hub, then commit package.json together with ${lockfile}`,
+  };
 }
 
 function copySkeleton(host: WorkspaceHost, skeletonRoot: string, plan: WorkspacePlanCreate): void {
@@ -670,8 +1042,52 @@ function assertCleanTree(host: WorkspaceHost, directory: string): void {
   }
 }
 
-function adoptHubFiles(host: WorkspaceHost, skeletonRoot: string, plan: WorkspacePlan & { advisorVersion: string }): void {
+/**
+ * An inventory document Launcher composed (from a choice, or a merge),
+ * checked again at write time by the same function every later read of it
+ * uses, so a document Launcher writes is always one Launcher reads back.
+ */
+function revalidatedDocument(document: string, hubOwner: string, label = "the chosen inventory"): string {
+  const validated = validateInventoryDocument(document, { hubOwner });
+  if (!validated.valid) throw new Error(`${label} ${validated.reason}`);
+  return document;
+}
+
+function adoptHubFiles(host: WorkspaceHost, skeletonRoot: string, plan: WorkspacePlanAdopt): readonly EnginePinChange[] {
   assertCleanTree(host, plan.directory);
+  // Resolve and strictly re-validate the inventory document BEFORE writing
+  // anything, including the hub marker -- planWorkspace already validated it
+  // once, but re-checking here (rather than trusting the earlier result)
+  // means a document that changed on disk between plan and apply still
+  // cannot land a mismatched shape, and it means this function alone
+  // guarantees "fail before any file is touched" (#1334).
+  let inventoryDocument: string | Uint8Array | undefined;
+  if (plan.action === "adopt" && plan.chosenInventory !== undefined) {
+    if (plan.chosenInventory.kind === "write") inventoryDocument = revalidatedDocument(plan.chosenInventory.document, plan.owner);
+  } else if (plan.action === "adopt" && plan.mergedInventoryDocument !== undefined) {
+    inventoryDocument = revalidatedDocument(plan.mergedInventoryDocument, plan.owner, "the merged inventory");
+  } else if (plan.action === "adopt" && plan.mergedInventoryRepositories !== undefined) {
+    // A plan carrying the merged entries without the rendered document: each entry is written whole, `packages`
+    // included, in the same layout renderInventoryDocument() writes; the contract check decides whether it is valid.
+    const repositories = plan.mergedInventoryRepositories;
+    inventoryDocument = revalidatedDocument(`${JSON.stringify({ schemaVersion: 1, repositories }, null, 2)}\n`, plan.owner, "the merged inventory");
+  } else if ("mergedInventoryIds" in plan && Array.isArray(plan.mergedInventoryIds)) {
+    // A plan built by hand with ids only: there are no entries to keep, so each id is written alone.
+    inventoryDocument = revalidatedDocument(renderInventoryDocument(plan.mergedInventoryIds.map((id) => ({ id }))), plan.owner, "the merged inventory");
+  } else if ("inventorySource" in plan && typeof plan.inventorySource === "string") {
+    const raw = host.readBytes(plan.inventorySource);
+    if (raw === null) throw new Error(`inventory source is not readable: ${plan.inventorySource}`);
+    const validated = validateInventoryDocument(raw, { hubOwner: plan.owner });
+    if (!validated.valid) throw new Error(`inventory source at ${plan.inventorySource} ${validated.reason}`);
+    if (validated.ids.length === 0) {
+      throw new Error(`inventory source at ${plan.inventorySource} must be a populated inventory document`);
+    }
+    // Copied byte for byte: the bytes just validated are the bytes written.
+    inventoryDocument = withFinalNewline(raw);
+  }
+  // The manifest is read and checked here too, for the same reason: mergeHubEnginePins refuses it only after
+  // the marker and the composed files are written, which would leave a half-appointed checkout.
+  assertManifestAppointable(host, plan.directory, skeletonRoot);
   const marker = {
     schemaVersion: 1,
     kind: "account-hub",
@@ -679,21 +1095,8 @@ 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 ("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");
-    }
-    writeSkeletonFile(host, plan.directory, WORKSPACE_INVENTORY_REL, raw.endsWith("\n") ? raw : `${raw}\n`);
-  }
+  if (typeof inventoryDocument === "string") writeSkeletonFile(host, plan.directory, WORKSPACE_INVENTORY_REL, inventoryDocument);
+  else if (inventoryDocument !== undefined) writeSkeletonBytes(host, plan.directory, WORKSPACE_INVENTORY_REL, inventoryDocument);
   if (host.readText(join(plan.directory, "AGENTS.md")) === null) {
     writeSkeletonFile(host, plan.directory, "AGENTS.md", CONSUMER_AGENTS_MD);
   } else {
@@ -710,7 +1113,15 @@ function adoptHubFiles(host: WorkspaceHost, skeletonRoot: string, plan: Workspac
     const ignore = host.readText(join(skeletonRoot, ".gitignore"));
     if (ignore !== null) writeSkeletonFile(host, plan.directory, ".gitignore", ignore);
   }
-  mergeAdvisorPin(host, plan.directory, skeletonRoot, plan.advisorVersion, plan.owner, plan.repository);
+  return mergeHubEnginePins(
+    host,
+    plan.directory,
+    skeletonRoot,
+    { advisorVersion: plan.advisorVersion, integratorVersion: plan.integratorVersion },
+    plan.owner,
+    plan.repository,
+    "appoint",
+  );
 }
 
 function requireZero(result: CommandResult, label: string): void {
@@ -721,9 +1132,11 @@ function requireZero(result: CommandResult, label: string): void {
 
 /**
  * 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.
+ * four dependency buckets for both hub engines (Advisor and Integrator);
+ * grades each pinned version against that engine's live registry version,
+ * when known, marking a pin older than live as a stale-pin finding and a
+ * degraded report. `liveIntegratorVersion` is the last parameter so earlier
+ * callers keep their argument positions.
  */
 export function reportHubHealth(
   host: WorkspaceHost,
@@ -732,78 +1145,123 @@ export function reportHubHealth(
   liveLauncherVersion?: string,
   retiredThisRun: readonly string[] = [],
   migration?: HubHealthReport["migration"],
+  liveIntegratorVersion?: string,
 ): HubHealthReport {
   const extra = new Set<string>();
-  const pins: Partial<Record<DependencyBucket, string>> = {};
+  const pins: Record<HubEnginePackage, Partial<Record<DependencyBucket, string>>> = {
+    [ADVISOR_PACKAGE]: {},
+    [INTEGRATOR_PACKAGE]: {},
+  };
   const manifestRaw = host.readText(join(directory, "package.json"));
   if (manifestRaw !== null) {
     try {
       const parsed: unknown = JSON.parse(manifestRaw);
       if (isRecord(parsed)) {
         for (const bucket of DEPENDENCY_BUCKETS) {
-          const pin = clossysNames(parsed[bucket], extra);
-          if (pin !== undefined) pins[bucket] = pin;
+          const found = enginePinsIn(parsed[bucket], extra);
+          for (const engine of HUB_ENGINE_PACKAGES) {
+            const pinned = found[engine];
+            if (pinned !== undefined) pins[engine][bucket] = pinned;
+          }
         }
       }
     } 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}` }]
-      : [];
-  });
+  const live: Record<HubEnginePackage, string | undefined> = {
+    [ADVISOR_PACKAGE]: liveAdvisorVersion,
+    [INTEGRATOR_PACKAGE]: liveIntegratorVersion,
+  };
+  const pinFindings: PinFinding[] = HUB_ENGINE_PACKAGES.flatMap((engine) =>
+    DEPENDENCY_BUCKETS.flatMap((bucket): PinFinding[] => {
+      const pinned = pins[engine][bucket];
+      const liveVersion = live[engine];
+      if (pinned === undefined || liveVersion === undefined) return [];
+      const comparison = compareVersions(pinned, liveVersion);
+      if (comparison === null) {
+        return [{ package: engine, bucket, pinned, grade: "indeterminate", note: `cannot compare ${pinned} with live ${liveVersion}` }];
+      }
+      return comparison < 0
+        ? [{ package: engine, bucket, pinned, grade: "stale", note: `pinned ${pinned} is older than live ${liveVersion}` }]
+        : [];
+    }),
+  );
+  const pinCount = (engine: HubEnginePackage): number => Object.values(pins[engine]).filter((value) => value !== undefined).length;
+  const misplaced = (engine: HubEnginePackage): boolean =>
+    pins[engine].devDependencies === undefined ||
+    pins[engine].dependencies !== undefined ||
+    pins[engine].optionalDependencies !== undefined ||
+    pins[engine].peerDependencies !== undefined;
+  const dualPin = HUB_ENGINE_PACKAGES.some((engine) => pinCount(engine) > 1);
   const skillsManifest = summarizeSkillsManifest(
     parseSkillManifest(host.readText(join(directory, SKILLS_MANIFEST_REL))),
     liveLauncherVersion,
     retiredThisRun,
   );
+  const enginePin = (engine: HubEnginePackage): HubEnginePin => {
+    const found = pins[engine];
+    const liveVersion = live[engine];
+    return {
+      ...(found.dependencies === undefined ? {} : { dependencies: found.dependencies }),
+      ...(found.devDependencies === undefined ? {} : { devDependencies: found.devDependencies }),
+      ...(found.optionalDependencies === undefined ? {} : { optionalDependencies: found.optionalDependencies }),
+      ...(found.peerDependencies === undefined ? {} : { peerDependencies: found.peerDependencies }),
+      ...(liveVersion === undefined ? {} : { live: liveVersion }),
+    };
+  };
+  const inventory = inspectInventory(host.readBytes(join(directory, WORKSPACE_INVENTORY_REL)), readHub(host, directory)?.owner);
   return {
     marker: readHub(host, directory) === undefined ? "missing" : "present",
-    inventory: inspectInventory(host.readText(join(directory, WORKSPACE_INVENTORY_REL))),
-    advisorPin: {
-      ...(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: Object.values(pins).filter((value) => value !== undefined).length > 1,
+    inventory,
+    advisorPin: enginePin(ADVISOR_PACKAGE),
+    integratorPin: enginePin(INTEGRATOR_PACKAGE),
+    dualPin,
     extraClossys: [...extra].sort(),
     pinFindings,
     degraded:
       pinFindings.some((finding) => finding.grade === "stale") ||
-      Object.values(pins).filter((value) => value !== undefined).length > 1 ||
-      pins.devDependencies === undefined ||
-      pins.dependencies !== undefined ||
-      pins.optionalDependencies !== undefined ||
-      pins.peerDependencies !== undefined,
+      dualPin ||
+      HUB_ENGINE_PACKAGES.some(misplaced) ||
+      inventory.status === "invalid",
     ...(migration === undefined ? {} : { migration }),
     skillsManifest,
   };
 }
 
-export function formatHubHealth(report: HubHealthReport): string {
+function formatEnginePin(pin: HubEnginePin): string {
   const pinParts: string[] = [];
   for (const bucket of DEPENDENCY_BUCKETS) {
-    const pinned = report.advisorPin[bucket];
+    const pinned = pin[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 pinned = pinParts.length === 0 ? "missing" : pinParts.join(" and ");
+  return `${pinned}${pin.live === undefined ? "" : `; live ${pin.live}`}`;
+}
+
+export function formatHubHealth(report: HubHealthReport): string {
   const extra = report.extraClossys.length === 0 ? "none" : report.extraClossys.join(", ");
   const inventory =
-    report.inventory.status === "populated" ? `populated (${report.inventory.count})` : report.inventory.status;
+    report.inventory.status === "populated"
+      ? `populated (${report.inventory.count})`
+      : report.inventory.status === "invalid"
+        ? `invalid${report.inventory.reason === undefined ? "" : ` -- ${report.inventory.reason}`}`
+        : report.inventory.status;
   const findings = report.pinFindings.map((finding) =>
-    finding.note !== undefined ? `${finding.bucket} ${finding.note}` : `${finding.bucket} ${finding.grade}`,
+    finding.note !== undefined
+      ? `${finding.package} ${finding.bucket} ${finding.note}`
+      : `${finding.package} ${finding.bucket} ${finding.grade}`,
   );
   const findingLine = findings.length === 0 ? "none" : findings.join("; ");
+  const enginePinLines =
+    report.enginePins === undefined
+      ? []
+      : [
+          `engine pins changed in package.json: ${report.enginePins.changed.map(describeEnginePinChange).join("; ")}`,
+          `next: ${report.enginePins.nextStep}`,
+        ];
+  const installLine =
+    report.installNeeded === undefined ? [] : [`install needed (${report.installNeeded.kind}): ${report.installNeeded.note}`];
   const skillParts: string[] = [];
   if (report.skillComposition !== undefined) {
     skillParts.push(
@@ -812,17 +1270,28 @@ export function formatHubHealth(report: HubHealthReport): string {
         : `skills composed: ${report.skillComposition.composed.map((name) => `clossys-${name}`).join(", ")}`,
     );
     for (const skip of report.skillComposition.skipped) {
+      // skip.packageDir names one of this package's own known package directories, never document text (see skills.ts).
       skillParts.push(`skill skipped (${skip.packageDir}): ${skip.note}`);
     }
+    // rosterTargets and siblings' inventoryId are already position-safe by
+    // the time they reach here: composeSkillRoster redacts every
+    // stored-inventory id to `inventoryPositionLabel()`'s position label
+    // before putting it in this report, because this whole report is also
+    // JSON-dumped into the `health:` line below -- an id left raw in the
+    // structured report would still reach the message that way even if this
+    // prose line named it safely.
     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}`);
+    for (const sibling of report.skillComposition.siblings ?? []) {
+      skillParts.push(`sibling (${sibling.inventoryId}): ${sibling.note}`);
     }
     if (report.skillComposition.retired !== undefined && report.skillComposition.retired.length > 0) {
       skillParts.push(`skills retired: ${report.skillComposition.retired.map((name) => `clossys-${name}`).join(", ")}`);
     }
+    for (const kept of report.skillComposition.preserved ?? []) {
+      skillParts.push(`skill preserved (clossys-${kept.packageDir}, not ${kept.action === "rewrite" ? "rewritten" : "retired"}): ${kept.note}`);
+    }
   }
   const skillsManifestLine =
     report.skillsManifest === undefined
@@ -841,14 +1310,17 @@ export function formatHubHealth(report: HubHealthReport): string {
       ? undefined
       : report.inventoryDrift.status === "indeterminate"
         ? `inventory drift: indeterminate${report.inventoryDrift.note === undefined ? "" : ` -- ${report.inventoryDrift.note}`}`
-        : `inventory drift: external-only ${report.inventoryDrift.externalOnly.length}, launcher-only ${report.inventoryDrift.launcherOnly.length}, agreeing ${report.inventoryDrift.agreeing.length}`;
+        : `inventory drift: external-only ${report.inventoryDrift.externalOnly.count}, launcher-only ${report.inventoryDrift.launcherOnly.count}, agreeing ${report.inventoryDrift.agreeing.count}`;
   return [
     `hub marker: ${report.marker}`,
     `inventory: ${inventory}`,
-    `advisor pin: ${pin}${live}`,
+    `advisor pin: ${formatEnginePin(report.advisorPin)}`,
+    `integrator pin: ${formatEnginePin(report.integratorPin)}`,
     `dual pin: ${report.dualPin ? "yes" : "no"}`,
     `extra @clossys/*: ${extra}`,
     `pin findings: ${findingLine}`,
+    ...enginePinLines,
+    ...installLine,
     `degraded: ${report.degraded ? "yes" : "no"}`,
     ...(migrationLine === undefined ? [] : [migrationLine]),
     ...(linkedHostsLine === undefined ? [] : [linkedHostsLine]),
@@ -863,20 +1335,36 @@ function withHealth(
   host: WorkspaceHost,
   directory: string,
   headline: string,
-  liveAdvisorVersion?: string,
-  skillComposition?: SkillCompositionResult & { linkedHosts?: readonly DiscoveredHost[] },
+  liveEngines: HubEngineVersions,
+  skillComposition?: SkillCompositionResult & {
+    linkedHosts?: readonly DiscoveredHost[];
+  },
   liveLauncherVersion?: string,
   migration?: HubHealthReport["migration"],
   inventoryDrift?: HubHealthReport["inventoryDrift"],
+  enginePinChanges: readonly EnginePinChange[] = [],
 ): WorkspaceApplyResult {
-  const base = reportHubHealth(host, directory, liveAdvisorVersion, liveLauncherVersion, skillComposition?.retired ?? [], migration);
-  const rosterSkipped = skillComposition?.rosterSkipped ?? [];
+  const base = reportHubHealth(
+    host,
+    directory,
+    liveEngines.advisorVersion,
+    liveLauncherVersion,
+    skillComposition?.retired ?? [],
+    migration,
+    liveEngines.integratorVersion,
+  );
+  const preserved = skillComposition?.preserved ?? [];
+  const installNeeded = engineInstallFinding(host, directory, enginePinChanges);
   const health: HubHealthReport = {
     ...base,
+    ...(enginePinChanges.length === 0
+      ? {}
+      : { enginePins: { changed: enginePinChanges, nextStep: enginePinNextStep(host, directory) } }),
+    ...(installNeeded === undefined ? {} : { installNeeded }),
     ...(skillComposition === undefined ? {} : { skillComposition }),
     ...(skillComposition?.linkedHosts === undefined ? {} : { linkedHosts: skillComposition.linkedHosts }),
     ...(inventoryDrift === undefined || inventoryDrift.status === "no-external-source" ? {} : { inventoryDrift }),
-    degraded: base.degraded || rosterSkipped.length > 0,
+    degraded: base.degraded || preserved.length > 0 || installNeeded !== undefined,
   };
   return {
     state: "satisfied",
@@ -891,8 +1379,8 @@ function withHealth(
  * 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);
+  const hubOwner = readHub(host, directory)?.owner;
+  const observation = inspectInventory(host.readBytes(join(directory, WORKSPACE_INVENTORY_REL)), hubOwner);
   if (observation.status !== "populated") {
     return { entries: [], skipped: true, note: `inventory is ${observation.status}; nothing to validate` };
   }
@@ -900,7 +1388,7 @@ export function checkInventoryEntries(host: WorkspaceHost, directory: string): I
   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(
+  const ids = readInventoryRepositories(host, join(directory, WORKSPACE_INVENTORY_REL), "the hub inventory", hubOwner).filter(
     (id) => id !== "",
   );
   const batch = 20;
@@ -924,6 +1412,7 @@ 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 === SIBLING_COMPOSING_CONSUMER_AGENTS_MD) return true;
   if (existing.includes("Run `npx @clossys/launcher` again to resume")) return true;
   return false;
 }
@@ -934,125 +1423,207 @@ function writeConsumerAgentsIfNeeded(host: WorkspaceHost, directory: string): vo
   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);
+/** What a hub run reports for each inventoried repository other than the hub. It never writes into one. */
+const SETUP_PULL_REQUEST_NOTE =
+  "a hub run writes nothing here; once this repository is staffed in an approved plan, @clossys-advisor and the voices of the roles staffed there arrive with that plan's setup pull request";
+const BESIDE_HUB_NOTE = `checkout beside the hub; ${SETUP_PULL_REQUEST_NOTE}`;
+const CLONE_NOT_BESIDE_HUB_NOTE = `not cloned beside the hub; ${SETUP_PULL_REQUEST_NOTE}`;
+
+/**
+ * Splits an inventory id into owner/repository, trusting a caller that
+ * already validated it with `isValidInventoryId` (every id reaching here
+ * comes from a document `validateInventoryDocument` already accepted)
+ * rather than re-deriving that rule -- but still runs it, so a caller that
+ * somehow supplies an unvalidated id gets `null`, never a wrong split.
+ */
+function parseInventoryRepositoryId(id: string, hubOwner: string): { owner: string; repository: string } | null {
+  if (!isValidInventoryId(id)) return null;
+  const slash = id.indexOf("/");
+  if (slash === -1) return { owner: hubOwner, repository: id };
+  return { owner: id.slice(0, slash), repository: id.slice(slash + 1) };
 }
 
-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";
+/** A checkout's origin as `owner/name`, when it is a github.com repository. */
+function originRepository(host: WorkspaceHost, directory: string): string | undefined {
+  const result = host.run("git", ["remote", "get-url", "origin"], { cwd: directory });
+  const remote = result.status === 0 ? parseGitHubRemote(result.stdout.trim()) : null;
+  return remote === null ? undefined : `${remote.owner}/${remote.repository}`;
+}
 
-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 };
+/**
+ * The hub's own repository identity: its origin's `owner/name`, or, when
+ * the checkout has no github.com origin, the repository its hub marker
+ * records. Never its folder path (see identity.ts).
+ */
+function hubRepositoryIdentity(host: WorkspaceHost, hubDirectory: string): string | undefined {
+  return originRepository(host, hubDirectory) ?? readHub(host, hubDirectory)?.repository;
 }
 
-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 }[];
-} {
+/** Where an inventoried repository other than the hub stands, as a hub run sees it. */
+type SiblingStatus =
+  | "beside-the-hub"
+  | "not-cloned"
+  | "other-account"
+  | "foundry-supplier-tree"
+  | "origin-mismatch"
+  | "not-a-git-checkout"
+  | "git-refused"
+  | "invalid-id"
+  | "inventory-invalid";
+
+/**
+ * `inventoryId` stays on every entry below for internal use only (a
+ * `gh repo clone` argument, a directory lookup, a structured result a
+ * caller inspects programmatically) -- never put directly in text a founder
+ * or agent reads. `position` is the id's 0-based index in the stored
+ * inventory's own `repositories` array; every message built from these
+ * entries (skill-roster lines, `--clone-missing` output) names that
+ * position instead, per the rule at the top of ./inventory-choice.ts.
+ * `position` is `undefined` only for the one entry below that is not a
+ * document id at all, the stored-inventory-file-itself failure.
+ */
+interface InventoriedSibling {
+  readonly inventoryId: string;
+  readonly position?: number;
+  readonly status: SiblingStatus;
+  readonly note: string;
+}
+
+/**
+ * Classifies every inventoried repository other than the hub. Read-only:
+ * it looks for a checkout beside the hub and reads that checkout's git
+ * origin, and nothing else, so a sibling's working tree, legacy output or
+ * old pins can neither change the result nor be changed by it. The hub run
+ * reports the result; only `--clone-missing` acts on it, and only on
+ * `not-cloned` entries.
+ */
+function classifyInventoriedSiblings(host: WorkspaceHost, hubDirectory: string, hubOwner: string): readonly InventoriedSibling[] {
   const parent = dirname(resolve(hubDirectory));
-  const hubResolved = resolve(hubDirectory);
-  const skipped: { inventoryId: string; note: string }[] = [];
-  const targets: { inventoryId: string; directory: string }[] = [];
+  const hubIdentity = hubRepositoryIdentity(host, hubDirectory);
+  const siblings: InventoriedSibling[] = [];
   const inventoryPath = join(hubDirectory, WORKSPACE_INVENTORY_REL);
   let inventoryIds: readonly string[];
   try {
-    inventoryIds = readInventoryRepositories(host, inventoryPath, "the hub inventory");
-  } catch {
-    return { targets: [], skipped: [] };
+    inventoryIds = readInventoryRepositories(host, inventoryPath, "the stored inventory", hubOwner);
+  } catch (error) {
+    // An invalid stored inventory is reported, never silently read for what
+    // it happens to look like -- no clone is attempted from it (#1334).
+    // WORKSPACE_INVENTORY_REL is Launcher's own constant path, not document
+    // content, so it is safe to name directly; there is no per-id position
+    // for a failure at the file level, so `position` stays undefined.
+    const reason = error instanceof Error ? error.message : String(error);
+    return [{ inventoryId: WORKSPACE_INVENTORY_REL, status: "inventory-invalid", note: reason }];
   }
-  for (const id of inventoryIds) {
-    if (id === "") continue;
+  for (const [position, id] of inventoryIds.entries()) {
     const parsed = parseInventoryRepositoryId(id, hubOwner);
     if (parsed === null) {
-      skipped.push({ inventoryId: id, note: "inventory id is not a valid repository slug" });
+      siblings.push({ inventoryId: id, position, status: "invalid-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" });
+    if (!belongsToOwner(id, hubOwner)) {
+      siblings.push({ inventoryId: id, position, status: "other-account", note: "other account; not this roster" });
       continue;
     }
+    // The hub itself is recognised by repository identity, not by folder path.
+    if (hubIdentity !== undefined && sameRepository(id, hubIdentity, hubOwner)) 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 });
+      siblings.push({ inventoryId: id, position, status: "not-cloned", note: CLONE_NOT_BESIDE_HUB_NOTE });
       continue;
     }
     if (looksLikeFoundry(host, candidate)) {
-      skipped.push({ inventoryId: id, note: "foundry supplier tree; skills are not written here" });
+      siblings.push({ inventoryId: id, position, status: "foundry-supplier-tree", 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" });
+    if (!host.exists(join(candidate, ".git"))) {
+      siblings.push({
+        inventoryId: id,
+        position,
+        status: "not-a-git-checkout",
+        note: "the folder beside the hub with this name is not a git checkout, so it cannot be matched to this inventory id",
+      });
       continue;
     }
-    targets.push({ inventoryId: id, directory: candidate });
+    const remote = host.run("git", ["remote", "get-url", "origin"], { cwd: candidate });
+    if (remote.status !== 0 && /dubious ownership/i.test(remote.stderr)) {
+      siblings.push({
+        inventoryId: id,
+        position,
+        status: "git-refused",
+        note: "git refuses to read this checkout (it reports dubious ownership), so its origin could not be matched to this inventory id",
+      });
+      continue;
+    }
+    const parsedOrigin = remote.status === 0 ? parseGitHubRemote(remote.stdout.trim()) : null;
+    const origin = parsedOrigin === null ? undefined : `${parsedOrigin.owner}/${parsedOrigin.repository}`;
+    if (origin === undefined || !sameRepository(origin, id, hubOwner)) {
+      siblings.push({ inventoryId: id, position, status: "origin-mismatch", note: "git origin does not match inventory id" });
+      continue;
+    }
+    siblings.push({ inventoryId: id, position, status: "beside-the-hub", note: BESIDE_HUB_NOTE });
   }
-  return { targets, skipped };
+  return siblings;
+}
+
+/** The position a message names instead of a document-sourced inventory id, matching `inventory-choice.ts`'s `listRemovedPositions`. `undefined` only for the stored-inventory-file-itself failure, which names the file by its own constant path instead. */
+export function inventoryPositionLabel(inventoryId: string, position: number | undefined): string {
+  return position === undefined ? inventoryId : `repositories[${position}] in the stored inventory`;
 }
 
 export interface CloneMissingOutcome {
+  /** Internal use only (a `gh repo clone` argument, a caller's own lookup) -- never put directly in a printed message; see `position`. */
   readonly inventoryId: string;
+  /** This id's 0-based position in the stored inventory's `repositories` array; what a message names instead of `inventoryId`. `undefined` only for the stored-inventory-file-itself failure. */
+  readonly position?: number;
   readonly result: "cloned" | "skipped-other-reason" | "failed";
   readonly note: string;
 }
 
 /**
  * Explicit, approved action (#1179, the #1045 pattern): clones every
- * inventoried repository that resolveSisterCloneTargets's own skip pass
- * identified as "just needs a clone" (CLONE_NOT_BESIDE_HUB_NOTE), and only
- * those -- every other skip reason (wrong account, foundry supplier tree,
- * origin mismatch, invalid slug) is left exactly as skipped, never
- * attempted. Never called from resume's default path; only from the
- * --clone-missing flag. Reverses the launcher README's own no-clone
- * default for exactly this one approved action.
+ * inventoried repository that classifyInventoriedSiblings found not cloned
+ * beside the hub, and only those -- every other reason (wrong account,
+ * foundry supplier tree, origin mismatch, invalid slug, invalid inventory)
+ * is reported as skipped, never attempted, and a checkout already beside
+ * the hub is left out. Never called from resume's default path; only from
+ * the --clone-missing flag. Reverses the launcher README's own no-clone
+ * default for exactly this one approved action. Cloning is not composing:
+ * a cloned repository receives its team only once it is staffed in an
+ * approved plan, with that plan's setup pull request.
  */
 export function cloneMissingInventoryRepositories(
   host: WorkspaceHost,
   hubDirectory: string,
   hubOwner: string,
 ): readonly CloneMissingOutcome[] {
-  const { skipped } = resolveSisterCloneTargets(host, hubDirectory, hubOwner);
   const parent = dirname(resolve(hubDirectory));
   const outcomes: CloneMissingOutcome[] = [];
-  for (const skip of skipped) {
-    if (skip.note !== CLONE_NOT_BESIDE_HUB_NOTE) {
-      outcomes.push({ inventoryId: skip.inventoryId, result: "skipped-other-reason", note: skip.note });
+  for (const skip of classifyInventoriedSiblings(host, hubDirectory, hubOwner)) {
+    if (skip.status === "beside-the-hub") continue;
+    if (skip.status !== "not-cloned") {
+      outcomes.push({ inventoryId: skip.inventoryId, position: skip.position, result: "skipped-other-reason", note: skip.note });
       continue;
     }
     const parsed = parseInventoryRepositoryId(skip.inventoryId, hubOwner);
     if (parsed === null) {
-      outcomes.push({ inventoryId: skip.inventoryId, result: "failed", note: "inventory id is not a valid repository slug" });
+      outcomes.push({ inventoryId: skip.inventoryId, position: skip.position, result: "failed", note: "inventory id is not a valid repository slug" });
       continue;
     }
+    // Cloning itself still uses the raw id and the real path -- that is the whole
+    // point of this action -- but the *reported* note never repeats either: the
+    // folder name comes straight from the inventory (a document), and `gh`'s own
+    // stderr on failure names the repository it could not find or clone. Both are
+    // fixed text instead (#1179); `position` is still how this outcome is named.
     const siblingPath = join(parent, parsed.repository);
     const result = host.run("gh", ["repo", "clone", `${hubOwner}/${parsed.repository}`, siblingPath]);
     if (result.status === 0) {
-      outcomes.push({ inventoryId: skip.inventoryId, result: "cloned", note: `cloned to ${siblingPath}` });
+      outcomes.push({ inventoryId: skip.inventoryId, position: skip.position, result: "cloned", note: "cloned beside the hub" });
     } else {
       outcomes.push({
         inventoryId: skip.inventoryId,
+        position: skip.position,
         result: "failed",
-        note: `gh repo clone exited ${result.status ?? "null"}: ${result.stderr.trim() || "no stderr"}`,
+        note: `gh repo clone exited ${result.status ?? "null"}`,
       });
     }
   }
@@ -1127,6 +1698,16 @@ function recordLinkedHosts(host: WorkspaceHost, directory: string): readonly Dis
   return linkedHosts;
 }
 
+/**
+ * Composes the team in the hub, and only the hub: this writes nothing into
+ * any checkout beside the hub. An inventoried product repository receives
+ * its skills, skills manifest, host discovery links and guidance only once
+ * it is staffed in an approved plan, with that plan's setup pull request. Each inventoried
+ * repository other than the hub is reported, read-only, as a sibling, named
+ * by its `inventoryPositionLabel()` position -- never its raw stored
+ * inventory id -- because the whole report is JSON-dumped into the apply
+ * message's `health:` line (see `formatHubHealth`).
+ */
 function composeSkillRoster(
   host: WorkspaceHost,
   hubDirectory: string,
@@ -1135,7 +1716,7 @@ function composeSkillRoster(
   options: { launcherPackageRoot: string; skillCatalogueRoot?: string; contractPath?: string },
 ): SkillCompositionResult & {
   readonly rosterTargets: readonly string[];
-  readonly rosterSkipped: readonly { readonly inventoryId: string; readonly note: string }[];
+  readonly siblings: readonly { readonly inventoryId: string; readonly note: string }[];
   readonly linkedHosts: readonly DiscoveredHost[];
 } {
   const composeOptions = {
@@ -1148,15 +1729,11 @@ function composeSkillRoster(
   writeConsumerAgentsIfNeeded(host, hubDirectory);
   writeClossysReadme(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) {
-    recordLinkedHosts(host, target.directory);
-    composeSkills(host, target.directory, composeOptions);
-    writeSisterConsumerAgentsIfNeeded(host, target.directory);
-    rosterTargets.push(target.inventoryId);
-  }
-  return { ...hubSkill, rosterTargets, rosterSkipped: skipped, linkedHosts };
+  const siblings = classifyInventoriedSiblings(host, hubDirectory, hubOwner)
+    // An invalid stored inventory is a hub finding: the health report's inventory line names it.
+    .filter((sibling) => sibling.status !== "inventory-invalid")
+    .map(({ inventoryId, position, note }) => ({ inventoryId: inventoryPositionLabel(inventoryId, position), note }));
+  return { ...hubSkill, rosterTargets: [hubId], siblings, linkedHosts };
 }
 
 function finishHubApply(
@@ -1166,11 +1743,12 @@ function finishHubApply(
   launcherPackageRoot: string,
   hubOwner: string,
   hubRepository: string,
-  liveAdvisorVersion?: string,
+  liveEngines: HubEngineVersions,
   skillCatalogueRoot?: string,
   contractPath?: string,
   liveLauncherVersion?: string,
   migration?: HubHealthReport["migration"],
+  enginePinChanges: readonly EnginePinChange[] = [],
 ): WorkspaceApplyResult {
   const skillComposition = composeSkillRoster(host, directory, hubOwner, hubRepository, {
     launcherPackageRoot,
@@ -1180,31 +1758,119 @@ function finishHubApply(
   // #1216: when the hub marker declares an external inventory, report drift against
   // it on every apply (create's fresh marker never declares one, so this is a no-op there).
   const hubDocument = readHub(host, directory);
-  const inventoryDrift = reportInventoryDrift(host, directory, hubDocument?.externalInventory, WORKSPACE_INVENTORY_REL);
-  return withHealth(host, directory, headline, liveAdvisorVersion, skillComposition, liveLauncherVersion, migration, inventoryDrift);
+  const inventoryDrift = reportInventoryDrift(host, directory, hubDocument?.externalInventory, WORKSPACE_INVENTORY_REL, hubOwner);
+  return withHealth(host, directory, headline, liveEngines, skillComposition, liveLauncherVersion, migration, inventoryDrift, enginePinChanges);
 }
 
 /**
  * Migrates a legacy `.clossys/` hub marker (and its sibling inventory, when
  * present) to `clossys/.state/`, then removes the old directory. Called only
  * when `locateHub` found the marker at the legacy path and nowhere else
- * (`plan.migrateFrom === "legacy"`); a hub with markers at both paths is
- * refused by `planWorkspace` before apply ever runs, so this never merges
- * two hub states.
+ * (`plan.migrateFrom === "legacy"`, or `classifyClonedHub` for a fresh
+ * clone); a hub with markers at both paths is refused by `planWorkspace`
+ * (or, for a clone, by `classifyClonedHub`) before anything is written, so
+ * this never merges two hub states.
  */
 function migrateLegacyHubState(host: WorkspaceHost, directory: string): HubHealthReport["migration"] {
   const markerRaw = host.readText(join(directory, LEGACY_WORKSPACE_MARKER_REL));
   if (markerRaw === null) return undefined;
   writeSkeletonFile(host, directory, WORKSPACE_MARKER_REL, markerRaw.endsWith("\n") ? markerRaw : `${markerRaw}\n`);
-  const inventoryRaw = host.readText(join(directory, LEGACY_WORKSPACE_INVENTORY_REL));
-  if (inventoryRaw !== null) {
-    writeSkeletonFile(host, directory, WORKSPACE_INVENTORY_REL, inventoryRaw.endsWith("\n") ? inventoryRaw : `${inventoryRaw}\n`);
-  }
+  // Moved byte for byte, so bytes that are not valid UTF-8 are still refused when read from the new place.
+  const inventoryBytes = host.readBytes(join(directory, LEGACY_WORKSPACE_INVENTORY_REL));
+  if (inventoryBytes !== null) writeSkeletonBytes(host, directory, WORKSPACE_INVENTORY_REL, withFinalNewline(inventoryBytes));
   host.remove(join(directory, LEGACY_STATE_DIR_REL));
   return { status: "migrated", from: LEGACY_STATE_DIR_REL, to: STATE_DIR_REL };
 }
 
-/** Applies a create, resume, or adopt plan through the host. Resume refreshes composed skills and stale AGENTS.md guidance. */
+/** The apply message's line saying what `--repositories` did to the inventory, or nothing without it. */
+function chosenInventoryNote(chosen: ChosenInventory | undefined): string {
+  return chosen === undefined ? "" : `\n${describeChosenInventory(chosen)}`;
+}
+
+function engineVersionsOf(plan: WorkspacePlan): HubEngineVersions {
+  return {
+    ...(plan.advisorVersion === undefined ? {} : { advisorVersion: plan.advisorVersion }),
+    ...(plan.integratorVersion === undefined ? {} : { integratorVersion: plan.integratorVersion }),
+  };
+}
+
+/**
+ * Classifies a freshly cloned `{owner}/workspace` (a resume plan with
+ * `clone: true`) by its marker, the way `planWorkspace` classifies a local
+ * checkout, and returns how apply must continue (#1585). It only reads: every
+ * refusal it decides is thrown here, before apply writes anything into the
+ * clone, and the appoint path's own refusals (a `package.json` that is not a
+ * JSON object among them) are thrown by `adoptHubFiles` before its first write.
+ *
+ * - both markers: refused, as `planWorkspace` refuses them locally;
+ * - a marker (current or legacy) for another owner: refused;
+ * - only the legacy marker: resume, migrating it;
+ * - only the current marker: resume;
+ * - no marker: an existing repository with unrelated content is being
+ *   appointed, so apply takes the adopt path, which keeps its files. That
+ *   path needs both engine versions, refuses the Foundry supplier tree, and
+ *   refuses an on-disk inventory that fails its contract (a missing or valid
+ *   one is kept as it is; this path writes no inventory), and refuses a
+ *   `package.json` that is not a JSON object (checked by `adoptHubFiles`).
+ */
+function classifyClonedHub(
+  host: WorkspaceHost,
+  plan: WorkspacePlanResume,
+): { kind: "resume"; migrateFrom?: "legacy" } | { kind: "appoint"; plan: WorkspacePlanAdopt } {
+  const located = locateHub(host, plan.directory);
+  if (located.migration === "indeterminate") {
+    throw new Error(
+      `in the cloned ${plan.owner}/${plan.repository}, both ${WORKSPACE_MARKER_REL} and the legacy ${LEGACY_WORKSPACE_MARKER_REL} are present; launcher never merges them silently -- remove one before resuming`,
+    );
+  }
+  if (located.document !== undefined) {
+    if (!sameOwner(located.document.owner, plan.owner)) {
+      throw new Error(
+        `the cloned ${plan.owner}/${plan.repository} carries a hub marker owned by "${located.document.owner}", not "${plan.owner}"; refusing to resume a hub for the wrong account`,
+      );
+    }
+    return located.migration === "legacy" ? { kind: "resume", migrateFrom: "legacy" } : { kind: "resume" };
+  }
+  if (!plan.advisorVersion) {
+    throw new Error(`cannot read a public ${ADVISOR_PACKAGE} version from the npm registry; appointing the cloned ${plan.owner}/${plan.repository} pins it`);
+  }
+  if (!plan.integratorVersion) {
+    throw new Error(`cannot read a public ${INTEGRATOR_PACKAGE} version from the npm registry; appointing the cloned ${plan.owner}/${plan.repository} pins it`);
+  }
+  if (looksLikeFoundry(host, plan.directory)) {
+    throw new Error(
+      `refusing to appoint the cloned ${plan.owner}/${plan.repository}: it looks like the Foundry supplier tree`,
+    );
+  }
+  const inventory = inspectInventory(host.readBytes(join(plan.directory, WORKSPACE_INVENTORY_REL)), plan.owner);
+  if (inventory.status === "invalid") {
+    throw new Error(
+      `the cloned ${plan.owner}/${plan.repository} has an on-disk hub inventory that ${inventory.reason ?? "does not conform to the inventory contract"}; fix or remove ${WORKSPACE_INVENTORY_REL} in that repository, then run launcher from inside the checkout`,
+    );
+  }
+  return {
+    kind: "appoint",
+    plan: {
+      action: "adopt",
+      owner: plan.owner,
+      repository: plan.repository,
+      directory: plan.directory,
+      advisorVersion: plan.advisorVersion,
+      integratorVersion: plan.integratorVersion,
+    },
+  };
+}
+
+/**
+ * Applies a create, resume, or adopt plan through the host. Resume refreshes
+ * composed skills and stale AGENTS.md guidance. A resume plan that clones
+ * (`clone: true`, planned from an empty directory) is classified only after
+ * the clone, by `classifyClonedHub`: a marked clone resumes (migrating a
+ * legacy marker), an unmarked one is appointed through the adopt path, and
+ * every refusal Launcher decides happens before anything is written into the clone (#1585).
+ * Every path writes only into the hub checkout, never into an inventoried
+ * repository beside it.
+ */
 export function applyWorkspacePlan(
   host: WorkspaceHost,
   plan: WorkspacePlan,
@@ -1216,25 +1882,40 @@ export function applyWorkspacePlan(
   const contractPath = options.contractPath;
   const liveLauncherVersion = options.liveLauncherVersion;
   if (plan.action === "resume") {
+    let migrateFrom = plan.migrateFrom;
     if (plan.clone) {
       requireZero(
         host.run("gh", ["repo", "clone", `${plan.owner}/${plan.repository}`, plan.directory]),
         "gh repo clone",
       );
+      const cloned = classifyClonedHub(host, plan);
+      if (cloned.kind === "appoint") return applyAdoptPlan(host, cloned.plan, skeletonRoot, options);
+      migrateFrom = cloned.migrateFrom;
+    }
+    const migration = migrateFrom === "legacy" ? migrateLegacyHubState(host, plan.directory) : undefined;
+    // --repositories (#1179): write the chosen inventory before composing, so
+    // this same run's health report lists the repositories just chosen.
+    if (plan.chosenInventory?.kind === "write") {
+      writeSkeletonFile(host, plan.directory, WORKSPACE_INVENTORY_REL, revalidatedDocument(plan.chosenInventory.document, plan.owner));
     }
-    const migration = plan.migrateFrom === "legacy" ? migrateLegacyHubState(host, plan.directory) : undefined;
+    // Resume raises the hub's engine pins to live: a frozen Advisor is
+    // bumped and Integrator is added, for each engine whose live version
+    // observeWorkspace could read. The health report says what changed and
+    // that the install, and a commit with the lockfile, come next.
+    const enginePinChanges = mergeHubEnginePins(host, plan.directory, skeletonRoot, engineVersionsOf(plan), plan.owner, plan.repository, "resume");
     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.`,
+      `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.${chosenInventoryNote(plan.chosenInventory)}`,
       launcherPackageRoot,
       plan.owner,
       plan.repository,
-      plan.advisorVersion,
+      engineVersionsOf(plan),
       skillCatalogueRoot,
       contractPath,
       liveLauncherVersion,
       migration,
+      enginePinChanges,
     );
   }
   if (plan.action === "create") {
@@ -1254,24 +1935,41 @@ export function applyWorkspacePlan(
       launcherPackageRoot,
       plan.owner,
       plan.repository,
-      plan.advisorVersion,
+      engineVersionsOf(plan),
       skillCatalogueRoot,
       contractPath,
       liveLauncherVersion,
     );
   }
-  adoptHubFiles(host, skeletonRoot, plan);
+  return applyAdoptPlan(host, plan, skeletonRoot, options);
+}
+
+/** Appoints an existing checkout as the hub, keeping its files: the adopt plan's apply, also reached from an unmarked clone (#1585). */
+function applyAdoptPlan(
+  host: WorkspaceHost,
+  plan: WorkspacePlanAdopt,
+  skeletonRoot: string,
+  options: ApplyWorkspaceOptions,
+): WorkspaceApplyResult {
+  const launcherPackageRoot = options.launcherPackageRoot ?? resolve(skeletonRoot, "..");
+  const { skillCatalogueRoot, contractPath, liveLauncherVersion } = options;
+  const enginePinChanges = adoptHubFiles(host, skeletonRoot, plan);
+  const inventoryReplacedNote = plan.replacesInvalidInventory === true
+    ? " The on-disk inventory failed schema validation; --inventory replaced it."
+    : "";
   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.`,
+    `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.${inventoryReplacedNote}${chosenInventoryNote(plan.chosenInventory)}`,
     launcherPackageRoot,
     plan.owner,
     plan.repository,
-    plan.advisorVersion,
+    engineVersionsOf(plan),
     skillCatalogueRoot,
     contractPath,
     liveLauncherVersion,
+    undefined,
+    enginePinChanges,
   );
 }