@clossys/launcher 0.3.0 → 0.4.0

package/dist/core.js

@@ -4,6 +4,9 @@ import { composeSkills, SKILLS_MANIFEST_REL } from "./skills.js";
 import { parseSkillManifest, summarizeSkillsManifest } from "./manifest.js";
 import { detectLinkedHosts, serializeHostRecord, HOSTS_REL } from "./hosts.js";
 import { reportInventoryDrift } from "./inventory-adoption.js";
+import { belongsToOwner, distinctOwners, sameOwner, sameRepository } from "./identity.js";
+import { isValidInventoryId, readInventoryDocument, renderInventoryDocument, validateInventoryDocument } 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. */
 export const CLOSSYS_DIR_REL = "clossys";
@@ -17,7 +20,10 @@ 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];
 const DEPENDENCY_BUCKETS = [
     "dependencies",
     "devDependencies",
@@ -38,6 +44,29 @@ 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
@@ -52,14 +81,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
 
@@ -174,7 +195,7 @@ export function isHubDocument(value) {
     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))
+    if (!parsed?.owner || !parsed.repository || !sameOwner(parsed.owner, value.owner) || !REPO.test(parsed.repository))
         return false;
     return true;
 }
@@ -195,8 +216,9 @@ function readHubAt(host, path) {
  * 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, directory) {
     const current = readHubAt(host, join(directory, WORKSPACE_MARKER_REL));
@@ -212,21 +234,26 @@ function locateHub(host, directory) {
 function readHub(host, directory) {
     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) {
+/**
+ * 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";
+/**
+ * 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, hubOwner) {
     if (raw === null)
         return { status: "missing", count: 0 };
-    try {
-        const parsed = 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, directory) {
     const manifestRaw = host.readText(join(directory, "package.json"));
@@ -263,19 +290,33 @@ function commandAvailable(host, command) {
 export function hasAdvisorPin(manifest) {
     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, name) {
+    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) {
-    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) {
     const cwd = host.cwd;
     const ghAvailable = commandAvailable(host, "gh");
@@ -292,39 +333,39 @@ export function observeWorkspace(host) {
             githubRepository = parsed.repository;
         }
     }
-    const candidates = new Set();
+    // Owners are compared as GitHub compares them (identity.ts): two spellings of one account are one candidate.
+    const seenOwners = [];
     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);
+            seenOwners.push(login);
         for (const org of stdoutLines(host.run("gh", ["org", "list"]))) {
             if (OWNER.test(org))
-                candidates.add(org);
+                seenOwners.push(org);
         }
     }
     if (githubOwner)
-        candidates.add(githubOwner);
+        seenOwners.push(githubOwner);
+    const candidates = new Set(distinctOwners(seenOwners));
     let remoteDefaultHub;
-    let advisorVersion;
     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 = hubLocation.migration === "legacy"
-        ? host.readText(join(cwd, LEGACY_WORKSPACE_INVENTORY_REL))
-        : host.readText(join(cwd, WORKSPACE_INVENTORY_REL));
+    const inventoryBytes = hubLocation.migration === "legacy"
+        ? host.readBytes(join(cwd, LEGACY_WORKSPACE_INVENTORY_REL))
+        : host.readBytes(join(cwd, WORKSPACE_INVENTORY_REL));
+    const inventoryOwner = hubLocation.document?.owner ?? githubOwner;
     const cwdObservation = {
         absolutePath: cwd,
         empty: isEffectivelyEmpty(entries),
@@ -334,7 +375,7 @@ export function observeWorkspace(host) {
         ...(hubLocation.document === undefined ? {} : { hub: hubLocation.document }),
         ...(hubLocation.migration === "none" ? {} : { hubMigration: hubLocation.migration }),
         looksLikeFoundry: looksLikeFoundry(host, cwd),
-        inventory: inspectInventory(inventoryRaw),
+        inventory: inspectInventory(inventoryBytes, inventoryOwner),
     };
     return {
         cwd: cwdObservation,
@@ -342,6 +383,7 @@ export function observeWorkspace(host) {
         ...(envOwner === undefined ? {} : { envOwner }),
         ...(remoteDefaultHub === undefined ? {} : { remoteDefaultHub }),
         ...(advisorVersion === undefined ? {} : { advisorVersion }),
+        ...(integratorVersion === undefined ? {} : { integratorVersion }),
         ghAvailable,
         gitAvailable,
     };
@@ -368,23 +410,37 @@ function resolveOwner(observation, host) {
  * 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, source, label) {
-    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, source, label, hubOwner) {
+    const raw = host.readBytes(source);
     if (raw === null)
         return [];
-    try {
-        const parsed = 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 = "") {
+    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`);
 }
 /**
  * Resolves which repositories the adopt plan inventories. When the on-disk hub
@@ -398,35 +454,92 @@ function resolveAdoptInventory(host, cwd, inventoryPath) {
     const trimmed = inventoryPath?.trim();
     const onDiskPopulated = cwd.inventory?.status === "populated";
     if (!onDiskPopulated && !trimmed) {
-        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");
+        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 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") {
-        return refuse("violated", "--inventory must point at a populated inventory document (schemaVersion 1, nonempty repositories)");
+    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 at ${resolved} must be a populated inventory document (nonempty repositories)`);
     }
-    if (!onDiskPopulated)
-        return { inventorySource: resolved };
+    if (!onDiskPopulated) {
+        return {
+            inventorySource: resolved,
+            ...(cwd.inventory?.status === "invalid" ? { replacesInvalidInventory: true } : {}),
+        };
+    }
+    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}`);
+    }
+    const onDiskEntries = 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 = [];
-    const seen = new Set();
-    for (const id of readInventoryRepositories(host, join(cwd.absolutePath, WORKSPACE_INVENTORY_REL), "the on-disk hub inventory")) {
-        if (id !== "" && !seen.has(id)) {
-            seen.add(id);
-            merged.push(id);
-        }
+    for (const entry of [...onDiskEntries, ...imported.entries]) {
+        if (!merged.some((kept) => sameRepository(kept.id, entry.id, cwd.githubOwner)))
+            merged.push(entry);
     }
-    for (const id of readInventoryRepositories(host, resolved, "--inventory")) {
-        if (id !== "" && !seen.has(id)) {
-            seen.add(id);
-            merged.push(id);
-        }
+    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, directory, owner, repositories, replaceInventory) {
+    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 };
+}
+/** The hub engine versions a plan carries, only those the observation read. */
+function observedEngineVersions(observation) {
+    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) {
+    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 { mergedInventoryIds: merged };
+    return { advisorVersion: observation.advisorVersion, integratorVersion: observation.integratorVersion };
 }
 export function planWorkspace(observation, host, options = {}) {
     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", `both ${WORKSPACE_MARKER_REL} and the legacy ${LEGACY_WORKSPACE_MARKER_REL} are present; launcher never merges them silently -- remove one before resuming`);
     }
@@ -436,26 +549,50 @@ export function planWorkspace(observation, host, options = {}) {
         cwd.hub === undefined &&
         cwd.git &&
         cwd.githubOwner !== undefined &&
-        cwd.githubOwner !== envOwner) {
+        !sameOwner(cwd.githubOwner, envOwner)) {
         return refuse("violated", `CLOSSYS_OWNER is "${envOwner}" but the github.com origin here is owned by "${cwd.githubOwner}"; refusing to appoint a marker for the wrong account`);
     }
     if (cwd.looksLikeFoundry) {
         return refuse("violated", "refusing to scaffold a hub inside the Foundry supplier tree; run from the GitHub repository you want to appoint, or from an empty directory");
     }
     if (cwd.hub) {
+        let chosen;
+        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" } : {}),
+            ...(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)
@@ -465,9 +602,12 @@ export function planWorkspace(observation, host, options = {}) {
             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) {
@@ -476,31 +616,37 @@ export function planWorkspace(observation, host, options = {}) {
     if (!cwd.empty) {
         return refuse("violated", "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,
     };
 }
 function containedPath(root, relativePath) {
@@ -515,76 +661,243 @@ function substitute(contents, plan) {
     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, directory, relativePath, contents) {
     const target = containedPath(directory, relativePath);
     host.mkdirp(dirname(target));
     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, directory, relativePath, contents) {
+    const target = containedPath(directory, relativePath);
+    host.mkdirp(dirname(target));
+    host.writeBytes(target, contents);
+}
+function withFinalNewline(bytes) {
+    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) {
     return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
 }
-function clossysNames(bucket, extra) {
+/**
+ * The hub engine pins in one dependency bucket, by engine. Every other
+ * `@clossys/*` name found there is added to `extra`.
+ */
+function enginePinsIn(bucket, extra) {
+    const pins = {};
     if (!isRecord(bucket))
-        return undefined;
-    let advisor;
+        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;
+}
+function engineVersionEntries(versions) {
+    const entries = [];
+    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) {
+    try {
+        const parsed = 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, directory, skeletonRoot) {
+    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(host, directory, skeletonRoot, advisorVersion, owner, repository) {
+function mergeHubEnginePins(host, directory, skeletonRoot, versions, owner, repository, mode) {
     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;
-    }
-    let manifest;
-    try {
-        const parsed = JSON.parse(raw);
-        if (!isRecord(parsed))
-            throw new Error("package.json is not an object");
-        manifest = parsed;
+        writeSkeletonFile(host, directory, "package.json", substitute(skeleton, { owner, repository, ...versions }));
+        return engineVersionEntries(versions).map(([engine, version]) => ({ package: engine, to: version }));
     }
-    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 = [];
+    for (const [engine, live] of engineVersionEntries(versions)) {
+        const devPin = isRecord(manifest.devDependencies) ? pinString(manifest.devDependencies[engine]) : undefined;
+        let movedFrom;
+        let movedPin;
+        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 = [
+    // 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) {
+    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, directory) {
+    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, directory, changes) {
+    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 = 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, skeletonRoot, plan) {
     for (const relativePath of SKELETON_FILES) {
@@ -616,8 +929,59 @@ function assertCleanTree(host, directory) {
         throw new Error(`${where} has uncommitted changes (git status --porcelain is nonempty); commit or stash them before appointing it as the account hub`);
     }
 }
+/**
+ * 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, hubOwner, label = "the chosen inventory") {
+    const validated = validateInventoryDocument(document, { hubOwner });
+    if (!validated.valid)
+        throw new Error(`${label} ${validated.reason}`);
+    return document;
+}
 function adoptHubFiles(host, skeletonRoot, plan) {
     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;
+    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",
@@ -625,17 +989,10 @@ function adoptHubFiles(host, skeletonRoot, plan) {
         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);
     }
@@ -655,7 +1012,7 @@ function adoptHubFiles(host, skeletonRoot, plan) {
         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, label) {
     if (result.status !== 0) {
@@ -664,22 +1021,30 @@ function requireZero(result, label) {
 }
 /**
  * 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, directory, liveAdvisorVersion, liveLauncherVersion, retiredThisRun = [], migration) {
+export function reportHubHealth(host, directory, liveAdvisorVersion, liveLauncherVersion, retiredThisRun = [], migration, liveIntegratorVersion) {
     const extra = new Set();
-    const pins = {};
+    const pins = {
+        [ADVISOR_PACKAGE]: {},
+        [INTEGRATOR_PACKAGE]: {},
+    };
     const manifestRaw = host.readText(join(directory, "package.json"));
     if (manifestRaw !== null) {
         try {
             const parsed = 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;
+                    }
                 }
             }
         }
@@ -687,71 +1052,114 @@ export function reportHubHealth(host, directory, liveAdvisorVersion, liveLaunche
             /* unreadable manifest is reported as missing pins */
         }
     }
-    const pinFindings = Object.entries(pins).flatMap(([bucket, pinned]) => {
-        if (liveAdvisorVersion === undefined)
+    const live = {
+        [ADVISOR_PACKAGE]: liveAdvisorVersion,
+        [INTEGRATOR_PACKAGE]: liveIntegratorVersion,
+    };
+    const pinFindings = HUB_ENGINE_PACKAGES.flatMap((engine) => DEPENDENCY_BUCKETS.flatMap((bucket) => {
+        const pinned = pins[engine][bucket];
+        const liveVersion = live[engine];
+        if (pinned === undefined || liveVersion === undefined)
             return [];
-        const comparison = compareVersions(pinned, liveAdvisorVersion);
+        const comparison = compareVersions(pinned, liveVersion);
         if (comparison === null) {
-            return [{ bucket: bucket, pinned, grade: "indeterminate", note: `cannot compare ${pinned} with live ${liveAdvisorVersion}` }];
+            return [{ package: engine, bucket, pinned, grade: "indeterminate", note: `cannot compare ${pinned} with live ${liveVersion}` }];
         }
         return comparison < 0
-            ? [{ bucket: bucket, pinned, grade: "stale", note: `pinned ${pinned} is older than live ${liveAdvisorVersion}` }]
+            ? [{ package: engine, bucket, pinned, grade: "stale", note: `pinned ${pinned} is older than live ${liveVersion}` }]
             : [];
-    });
+    }));
+    const pinCount = (engine) => Object.values(pins[engine]).filter((value) => value !== undefined).length;
+    const misplaced = (engine) => 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) => {
+        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) {
+function formatEnginePin(pin) {
     const pinParts = [];
     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) {
     const extra = report.extraClossys.length === 0 ? "none" : report.extraClossys.join(", ");
-    const inventory = report.inventory.status === "populated" ? `populated (${report.inventory.count})` : report.inventory.status;
-    const findings = report.pinFindings.map((finding) => finding.note !== undefined ? `${finding.bucket} ${finding.note}` : `${finding.bucket} ${finding.grade}`);
+    const inventory = 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.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 = [];
     if (report.skillComposition !== undefined) {
         skillParts.push(report.skillComposition.composed.length === 0
             ? "skills composed: none"
             : `skills composed: ${report.skillComposition.composed.map((name) => `clossys-${name}`).join(", ")}`);
         for (const skip of report.skillComposition.skipped) {
+            // 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
         ? undefined
@@ -766,14 +1174,17 @@ export function formatHubHealth(report) {
         ? 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]),
@@ -783,15 +1194,20 @@ export function formatHubHealth(report) {
         `health: ${JSON.stringify(report)}`,
     ].join("\n");
 }
-function withHealth(host, directory, headline, liveAdvisorVersion, skillComposition, liveLauncherVersion, migration, inventoryDrift) {
-    const base = reportHubHealth(host, directory, liveAdvisorVersion, liveLauncherVersion, skillComposition?.retired ?? [], migration);
-    const rosterSkipped = skillComposition?.rosterSkipped ?? [];
+function withHealth(host, directory, headline, liveEngines, skillComposition, liveLauncherVersion, migration, inventoryDrift, enginePinChanges = []) {
+    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 = {
         ...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",
@@ -805,8 +1221,8 @@ function withHealth(host, directory, headline, liveAdvisorVersion, skillComposit
  * a note; marks ids whose check fails as unknown. Never mutates the inventory.
  */
 export function checkInventoryEntries(host, directory) {
-    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` };
     }
@@ -814,7 +1230,7 @@ export function checkInventoryEntries(host, directory) {
     if (!available) {
         return { entries: [], skipped: true, note: "`gh` is unavailable; inventory ids were not validated" };
     }
-    const ids = readInventoryRepositories(host, join(directory, WORKSPACE_INVENTORY_REL), "the hub inventory").filter((id) => id !== "");
+    const ids = readInventoryRepositories(host, join(directory, WORKSPACE_INVENTORY_REL), "the hub inventory", hubOwner).filter((id) => id !== "");
     const batch = 20;
     const entries = [];
     for (let index = 0; index < ids.length; index += batch) {
@@ -840,6 +1256,8 @@ function shouldRefreshConsumerAgents(existing) {
         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;
@@ -850,111 +1268,163 @@ function writeConsumerAgentsIfNeeded(host, directory) {
         return;
     writeSkeletonFile(host, directory, "AGENTS.md", CONSUMER_AGENTS_MD);
 }
-function writeSisterConsumerAgentsIfNeeded(host, directory) {
-    const existing = host.readText(join(directory, "AGENTS.md"));
-    if (existing !== null && existing.trim() !== "" && existing !== SISTER_CONSUMER_AGENTS_MD)
-        return;
-    writeSkeletonFile(host, directory, "AGENTS.md", SISTER_CONSUMER_AGENTS_MD);
-}
-const CLONE_NOT_BESIDE_HUB_NOTE = "clone not next to the hub; voices appear here after this repository is cloned beside the hub and launcher resumes";
+/** 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, hubOwner) {
-    const trimmed = id.trim();
-    if (trimmed === "")
+    if (!isValidInventoryId(id))
         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 };
+    const slash = id.indexOf("/");
+    if (slash === -1)
+        return { owner: hubOwner, repository: id };
+    return { owner: id.slice(0, slash), repository: id.slice(slash + 1) };
+}
+/** A checkout's origin as `owner/name`, when it is a github.com repository. */
+function originRepository(host, directory) {
+    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 resolveSisterCloneTargets(host, hubDirectory, hubOwner) {
+/**
+ * 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, hubDirectory) {
+    return originRepository(host, hubDirectory) ?? readHub(host, hubDirectory)?.repository;
+}
+/**
+ * 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, hubDirectory, hubOwner) {
     const parent = dirname(resolve(hubDirectory));
-    const hubResolved = resolve(hubDirectory);
-    const skipped = [];
-    const targets = [];
+    const hubIdentity = hubRepositoryIdentity(host, hubDirectory);
+    const siblings = [];
     const inventoryPath = join(hubDirectory, WORKSPACE_INVENTORY_REL);
     let inventoryIds;
     try {
-        inventoryIds = readInventoryRepositories(host, inventoryPath, "the hub inventory");
-    }
-    catch {
-        return { targets: [], skipped: [] };
-    }
-    for (const id of inventoryIds) {
-        if (id === "")
-            continue;
+        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 [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;
         }
-        const candidate = join(parent, parsed.repository);
-        const candidateResolved = resolve(candidate);
-        if (candidateResolved === hubResolved)
+        // 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);
         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, position) {
+    return position === undefined ? inventoryId : `repositories[${position}] in the stored inventory`;
 }
 /**
  * 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, hubDirectory, hubOwner) {
-    const { skipped } = resolveSisterCloneTargets(host, hubDirectory, hubOwner);
     const parent = dirname(resolve(hubDirectory));
     const outcomes = [];
-    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"}`,
             });
         }
     }
@@ -1021,6 +1491,16 @@ function recordLinkedHosts(host, directory) {
     writeSkeletonFile(host, directory, HOSTS_REL, serializeHostRecord({ schemaVersion: 1, linkedHosts, recordedAt: host.now() }));
     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, hubDirectory, hubOwner, hubRepository, options) {
     const composeOptions = {
         launcherPackageRoot: options.launcherPackageRoot,
@@ -1032,17 +1512,13 @@ function composeSkillRoster(host, hubDirectory, hubOwner, hubRepository, options
     writeConsumerAgentsIfNeeded(host, hubDirectory);
     writeClossysReadme(host, hubDirectory);
     const hubId = hubRosterId(host, hubDirectory, hubOwner, hubRepository);
-    const rosterTargets = [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(host, directory, headline, launcherPackageRoot, hubOwner, hubRepository, liveAdvisorVersion, skillCatalogueRoot, contractPath, liveLauncherVersion, migration) {
+function finishHubApply(host, directory, headline, launcherPackageRoot, hubOwner, hubRepository, liveEngines, skillCatalogueRoot, contractPath, liveLauncherVersion, migration, enginePinChanges = []) {
     const skillComposition = composeSkillRoster(host, directory, hubOwner, hubRepository, {
         launcherPackageRoot,
         ...(skillCatalogueRoot === undefined ? {} : { skillCatalogueRoot }),
@@ -1051,49 +1527,148 @@ function finishHubApply(host, directory, headline, launcherPackageRoot, hubOwner
     // #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, directory) {
     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) {
+    return chosen === undefined ? "" : `\n${describeChosenInventory(chosen)}`;
+}
+function engineVersionsOf(plan) {
+    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, plan) {
+    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, plan, skeletonRoot, options = {}) {
     const launcherPackageRoot = options.launcherPackageRoot ?? resolve(skeletonRoot, "..");
     const skillCatalogueRoot = options.skillCatalogueRoot;
     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 = plan.migrateFrom === "legacy" ? migrateLegacyHubState(host, plan.directory) : undefined;
-        return finishHubApply(host, plan.directory, `resumed ${plan.owner}/${plan.repository} as the account hub\nOpen this folder in your coding agent. Advisor stays read-only until you approve a next action.`, launcherPackageRoot, plan.owner, plan.repository, plan.advisorVersion, skillCatalogueRoot, contractPath, liveLauncherVersion, migration);
+        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));
+        }
+        // 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.${chosenInventoryNote(plan.chosenInventory)}`, launcherPackageRoot, plan.owner, plan.repository, engineVersionsOf(plan), skillCatalogueRoot, contractPath, liveLauncherVersion, migration, enginePinChanges);
     }
     if (plan.action === "create") {
         copySkeleton(host, skeletonRoot, plan);
         requireZero(host.run("gh", ["repo", "create", `${plan.owner}/${plan.repository}`, "--private", "--source", plan.directory, "--remote", "origin", "--push"], { cwd: plan.directory }), "gh repo create");
-        return finishHubApply(host, plan.directory, `created ${plan.owner}/${plan.repository} as the account hub\nOpen this folder in your coding agent. Advisor stays read-only until you approve a next action.`, launcherPackageRoot, plan.owner, plan.repository, plan.advisorVersion, skillCatalogueRoot, contractPath, liveLauncherVersion);
+        return finishHubApply(host, plan.directory, `created ${plan.owner}/${plan.repository} as the account hub\nOpen this folder in your coding agent. Advisor stays read-only until you approve a next action.`, launcherPackageRoot, plan.owner, plan.repository, engineVersionsOf(plan), skillCatalogueRoot, contractPath, liveLauncherVersion);
     }
-    adoptHubFiles(host, skeletonRoot, plan);
-    return finishHubApply(host, plan.directory, `appointed ${plan.owner}/${plan.repository} as the account hub\nExisting project files were kept. This hub inventories engagement; it does not install the catalogue into the repo.`, launcherPackageRoot, plan.owner, plan.repository, plan.advisorVersion, skillCatalogueRoot, contractPath, liveLauncherVersion);
+    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, plan, skeletonRoot, options) {
+    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.${inventoryReplacedNote}${chosenInventoryNote(plan.chosenInventory)}`, launcherPackageRoot, plan.owner, plan.repository, engineVersionsOf(plan), skillCatalogueRoot, contractPath, liveLauncherVersion, undefined, enginePinChanges);
 }
 export function launcherPackageRootFromModule(moduleUrl) {
     return resolve(dirname(fileURLToPath(moduleUrl)), "..");