@clossys/launcher 0.1.2 → 0.3.0

package/dist/core.js

@@ -1,9 +1,23 @@
 import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+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";
 export const DEFAULT_REPOSITORY_NAME = "workspace";
-export const WORKSPACE_MARKER_REL = ".clossys/workspace.json";
-export const WORKSPACE_INVENTORY_REL = ".clossys/inventory.json";
+/** The one visible, per-repository Clossys folder (#1171). Every role's output lives under it. */
+export const CLOSSYS_DIR_REL = "clossys";
+/** Machine files only: hub marker, inventory, skills manifest. Visible (not dot-hidden) so it is easy to find, but not a place a person edits by hand. */
+export const STATE_DIR_REL = join(CLOSSYS_DIR_REL, ".state");
+export const WORKSPACE_MARKER_REL = join(STATE_DIR_REL, "workspace.json");
+export const WORKSPACE_INVENTORY_REL = join(STATE_DIR_REL, "inventory.json");
+export const CLOSSYS_README_REL = join(CLOSSYS_DIR_REL, "README.md");
+/** Pre-#1171 machine-state directory. Resume migrates it automatically; see `locateHub`. */
+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 LAUNCHER_PACKAGE = "@clossys/launcher";
 const DEPENDENCY_BUCKETS = [
     "dependencies",
     "devDependencies",
@@ -22,10 +36,52 @@ const SKELETON_FILES = [
 /** Written at generate time so this package never ships a nested AGENTS.md. */
 export const CONSUMER_AGENTS_MD = `# Account workspace
 
+This folder is the account hub for Foundry packages.
+
+After \`npx @clossys/launcher\`, the same \`@clossys-*\` team is composed in
+every inventoried checkout beside this hub. Talk with \`@clossys-advisor\` and
+\`@clossys-<package>\` here or in a product repository. A missing \`@\` mention
+is not how we signal incompatibility — \`@clossys-advisor\` is the hiring check.
+
+Run \`npx @clossys/launcher\` again for hub health and to refresh voices on
+clones next to the hub, not as how you talk to packages.
+
+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.
+`;
+/** Canned guidance for inventoried product checkouts (not the hub). */
+export const SISTER_CONSUMER_AGENTS_MD = `# Product repository
+
+This repository is part of the same account engagement. The same
+\`@clossys-<package>\` team is here for intro and questions;
+\`@clossys-advisor\` decides hiring and compatibility. This folder is not the
+hub — engines are hired per repository, not dumped here.
+`;
+/** Previous generate-time guidance; used to refresh stale hub AGENTS.md on resume. */
+export const LEGACY_CONSUMER_AGENTS_MD = `# Account workspace
+
 This repository is the account hub for Foundry packages. It inventories
 where packages are installed and coordinates engagement. It is not a
 product application and does not need the whole catalogue installed here.
 
+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.
+
+When there is a next step, say only:
+
+1. Where we are (one sentence).
+2. What you should do next (one sentence).
+3. What we will not do until you say yes.
+4. Whether anything will be saved to git (usually no).
+
+Wait for a plain yes before changing files. "Approved" in chat is
+permission for that one step only. It is not a lasting grant and it
+does not become a commit unless someone later saves a file.
+
 Open this folder in your coding agent. Advisor is read-only until you
 approve a next action.
 
@@ -122,8 +178,8 @@ export function isHubDocument(value) {
         return false;
     return true;
 }
-function readHub(host, directory) {
-    const raw = host.readText(join(directory, WORKSPACE_MARKER_REL));
+function readHubAt(host, path) {
+    const raw = host.readText(path);
     if (raw === null)
         return undefined;
     try {
@@ -134,7 +190,29 @@ function readHub(host, directory) {
         return undefined;
     }
 }
-/** Classifies a generated hub inventory (packed template skeleton/.clossys/inventory.json; the generated path does not ship) without inventing repositories. */
+/**
+ * Locates the hub marker across the `.clossys/` -> `clossys/.state/`
+ * 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.
+ */
+function locateHub(host, directory) {
+    const current = readHubAt(host, join(directory, WORKSPACE_MARKER_REL));
+    const legacy = readHubAt(host, join(directory, LEGACY_WORKSPACE_MARKER_REL));
+    if (current !== undefined && legacy !== undefined)
+        return { migration: "indeterminate" };
+    if (current !== undefined)
+        return { document: current, migration: "clean" };
+    if (legacy !== undefined)
+        return { document: legacy, migration: "legacy" };
+    return { migration: "none" };
+}
+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) {
     if (raw === null)
         return { status: "missing", count: 0 };
@@ -188,6 +266,16 @@ export function hasAdvisorPin(manifest) {
     return DEPENDENCY_BUCKETS.some((bucket) => clossysNames(manifest[bucket], new Set()) !== 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;
+}
 export function observeWorkspace(host) {
     const cwd = host.cwd;
     const ghAvailable = commandAvailable(host, "gh");
@@ -227,24 +315,26 @@ export function observeWorkspace(host) {
         if (viewed.status === 0)
             remoteDefaultHub = { owner: ownerGuess, repository: DEFAULT_REPOSITORY_NAME };
     }
-    // Skip the registry read when the tree already pins Advisor in some bucket:
-    // adopt leaves an existing pin alone, so no live version is needed to plan it.
-    const manifestPinsAdvisor = hasAdvisorPin(readJson(host, join(cwd, "package.json")));
-    if (!manifestPinsAdvisor) {
-        const viewedAdvisor = host.run("npm", ["view", ADVISOR_PACKAGE, "version"]);
-        const version = viewedAdvisor.stdout.trim();
-        if (viewedAdvisor.status === 0 && /^\d+\.\d+\.\d+$/.test(version))
-            advisorVersion = version;
-    }
+    const 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 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 cwdObservation = {
         absolutePath: cwd,
         empty: isEffectivelyEmpty(entries),
         git,
         ...(githubOwner === undefined ? {} : { githubOwner }),
         ...(githubRepository === undefined ? {} : { githubRepository }),
-        ...(readHub(host, cwd) === undefined ? {} : { hub: readHub(host, cwd) }),
+        ...(hubLocation.document === undefined ? {} : { hub: hubLocation.document }),
+        ...(hubLocation.migration === "none" ? {} : { hubMigration: hubLocation.migration }),
         looksLikeFoundry: looksLikeFoundry(host, cwd),
-        inventory: inspectInventory(host.readText(join(cwd, WORKSPACE_INVENTORY_REL))),
+        inventory: inspectInventory(inventoryRaw),
     };
     return {
         cwd: cwdObservation,
@@ -278,7 +368,7 @@ 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.
  */
-function readInventoryRepositories(host, source, label) {
+export function readInventoryRepositories(host, source, label) {
     const raw = host.readText(source);
     if (raw === null)
         return [];
@@ -308,7 +398,7 @@ 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/inventory.json; the generated path does not ship), or --inventory <path> to a populated inventory document");
+        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 (!trimmed)
         return {};
@@ -337,6 +427,9 @@ function resolveAdoptInventory(host, cwd, inventoryPath) {
 }
 export function planWorkspace(observation, host, options = {}) {
     const { cwd } = observation;
+    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`);
+    }
     const envOwner = observation.envOwner ?? (host.env.CLOSSYS_OWNER?.trim() || undefined);
     if (envOwner !== undefined &&
         !cwd.looksLikeFoundry &&
@@ -356,6 +449,8 @@ export function planWorkspace(observation, host, options = {}) {
             repository: repoNameFromSlug(cwd.hub.repository, DEFAULT_REPOSITORY_NAME),
             directory: cwd.absolutePath,
             clone: false,
+            ...(observation.advisorVersion === undefined ? {} : { advisorVersion: observation.advisorVersion }),
+            ...(cwd.hubMigration === "legacy" ? { migrateFrom: "legacy" } : {}),
         };
     }
     if (cwd.git && cwd.githubOwner && cwd.githubRepository) {
@@ -391,6 +486,7 @@ export function planWorkspace(observation, host, options = {}) {
             repository: observation.remoteDefaultHub.repository,
             directory: cwd.absolutePath,
             clone: true,
+            ...(observation.advisorVersion === undefined ? {} : { advisorVersion: observation.advisorVersion }),
         };
     }
     if (!observation.ghAvailable) {
@@ -411,7 +507,7 @@ function containedPath(root, relativePath) {
     const resolved = resolve(root, relativePath);
     const prefix = root.endsWith(sep) ? root : `${root}${sep}`;
     if (resolved !== root && !resolved.startsWith(prefix)) {
-        throw new Error(`refusing to write outside the hub directory: ${relativePath}`);
+        throw new Error(`refusing to write outside the workspace directory: ${relativePath}`);
     }
     return resolved;
 }
@@ -443,15 +539,20 @@ function clossysNames(bucket, extra) {
     }
     return advisor;
 }
-/** Leaves an existing Advisor pin in whichever bucket it already occupies. */
-function mergeAdvisorPin(host, directory, skeletonRoot, advisorVersion, repository) {
+/**
+ * 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`.
+ */
+function mergeAdvisorPin(host, directory, skeletonRoot, advisorVersion, owner, repository) {
     const path = join(directory, "package.json");
     const raw = host.readText(path);
     if (raw === null) {
         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, repository, advisorVersion }));
+        writeSkeletonFile(host, directory, "package.json", substitute(skeleton, { owner, repository, advisorVersion }));
         return;
     }
     let manifest;
@@ -464,13 +565,25 @@ function mergeAdvisorPin(host, directory, skeletonRoot, advisorVersion, reposito
     catch {
         throw new Error("existing package.json is unreadable JSON");
     }
-    const extra = new Set();
-    const pinnedSomewhere = DEPENDENCY_BUCKETS.some((bucket) => clossysNames(manifest[bucket], extra) !== undefined);
-    if (pinnedSomewhere)
-        return;
+    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) {
+        manifest.name = `@${owner}/${repository}`;
+    }
     host.writeText(path, `${JSON.stringify(manifest, null, 2)}\n`);
 }
 function copySkeleton(host, skeletonRoot, plan) {
@@ -526,6 +639,9 @@ function adoptHubFiles(host, skeletonRoot, plan) {
     if (host.readText(join(plan.directory, "AGENTS.md")) === null) {
         writeSkeletonFile(host, plan.directory, "AGENTS.md", CONSUMER_AGENTS_MD);
     }
+    else {
+        writeConsumerAgentsIfNeeded(host, plan.directory);
+    }
     if (host.readText(join(plan.directory, "CLAUDE.md")) === null) {
         writeSkeletonFile(host, plan.directory, "CLAUDE.md", CONSUMER_CLAUDE_MD);
     }
@@ -539,7 +655,7 @@ function adoptHubFiles(host, skeletonRoot, plan) {
         if (ignore !== null)
             writeSkeletonFile(host, plan.directory, ".gitignore", ignore);
     }
-    mergeAdvisorPin(host, plan.directory, skeletonRoot, plan.advisorVersion, plan.repository);
+    mergeAdvisorPin(host, plan.directory, skeletonRoot, plan.advisorVersion, plan.owner, plan.repository);
 }
 function requireZero(result, label) {
     if (result.status !== 0) {
@@ -552,7 +668,7 @@ function requireZero(result, label) {
  * registry version, marking a pin older than live as a stale-pin finding and a
  * degraded report.
  */
-export function reportHubHealth(host, directory, liveAdvisorVersion) {
+export function reportHubHealth(host, directory, liveAdvisorVersion, liveLauncherVersion, retiredThisRun = [], migration) {
     const extra = new Set();
     const pins = {};
     const manifestRaw = host.readText(join(directory, "package.json"));
@@ -582,6 +698,7 @@ export function reportHubHealth(host, directory, liveAdvisorVersion) {
             ? [{ bucket: bucket, pinned, grade: "stale", note: `pinned ${pinned} is older than live ${liveAdvisorVersion}` }]
             : [];
     });
+    const skillsManifest = summarizeSkillsManifest(parseSkillManifest(host.readText(join(directory, SKILLS_MANIFEST_REL))), liveLauncherVersion, retiredThisRun);
     return {
         marker: readHub(host, directory) === undefined ? "missing" : "present",
         inventory: inspectInventory(host.readText(join(directory, WORKSPACE_INVENTORY_REL))),
@@ -595,7 +712,14 @@ export function reportHubHealth(host, directory, liveAdvisorVersion) {
         dualPin: Object.values(pins).filter((value) => value !== undefined).length > 1,
         extraClossys: [...extra].sort(),
         pinFindings,
-        degraded: pinFindings.some((finding) => finding.grade === "stale"),
+        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,
+        ...(migration === undefined ? {} : { migration }),
+        skillsManifest,
     };
 }
 export function formatHubHealth(report) {
@@ -611,6 +735,38 @@ export function formatHubHealth(report) {
     const inventory = report.inventory.status === "populated" ? `populated (${report.inventory.count})` : report.inventory.status;
     const findings = report.pinFindings.map((finding) => finding.note !== undefined ? `${finding.bucket} ${finding.note}` : `${finding.bucket} ${finding.grade}`);
     const findingLine = findings.length === 0 ? "none" : findings.join("; ");
+    const skillParts = [];
+    if (report.skillComposition !== undefined) {
+        skillParts.push(report.skillComposition.composed.length === 0
+            ? "skills composed: none"
+            : `skills composed: ${report.skillComposition.composed.map((name) => `clossys-${name}`).join(", ")}`);
+        for (const skip of report.skillComposition.skipped) {
+            skillParts.push(`skill skipped (${skip.packageDir}): ${skip.note}`);
+        }
+        if (report.skillComposition.rosterTargets !== undefined && report.skillComposition.rosterTargets.length > 0) {
+            skillParts.push(`skill roster written: ${report.skillComposition.rosterTargets.join(", ")}`);
+        }
+        for (const skip of report.skillComposition.rosterSkipped ?? []) {
+            skillParts.push(`skill roster skipped (${skip.inventoryId}): ${skip.note}`);
+        }
+        if (report.skillComposition.retired !== undefined && report.skillComposition.retired.length > 0) {
+            skillParts.push(`skills retired: ${report.skillComposition.retired.map((name) => `clossys-${name}`).join(", ")}`);
+        }
+    }
+    const skillsManifestLine = report.skillsManifest === undefined
+        ? undefined
+        : report.skillsManifest.status === "missing"
+            ? "skills manifest: missing"
+            : `skills: ${report.skillsManifest.stale} out of date, ${report.skillsManifest.retired} retired (${report.skillsManifest.total} composed)`;
+    const migrationLine = report.migration === undefined ? undefined : `migration: moved hub state from ${report.migration.from} to ${report.migration.to}`;
+    const linkedHostsLine = report.linkedHosts === undefined
+        ? undefined
+        : `linked hosts: ${report.linkedHosts.length === 0 ? "none detected" : report.linkedHosts.join(", ")}`;
+    const inventoryDriftLine = report.inventoryDrift === undefined
+        ? 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}`;
     return [
         `hub marker: ${report.marker}`,
         `inventory: ${inventory}`,
@@ -619,9 +775,30 @@ export function formatHubHealth(report) {
         `extra @clossys/*: ${extra}`,
         `pin findings: ${findingLine}`,
         `degraded: ${report.degraded ? "yes" : "no"}`,
+        ...(migrationLine === undefined ? [] : [migrationLine]),
+        ...(linkedHostsLine === undefined ? [] : [linkedHostsLine]),
+        ...(inventoryDriftLine === undefined ? [] : [inventoryDriftLine]),
+        ...(skillsManifestLine === undefined ? [] : [skillsManifestLine]),
+        ...(skillParts.length === 0 ? [] : skillParts),
         `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 ?? [];
+    const health = {
+        ...base,
+        ...(skillComposition === undefined ? {} : { skillComposition }),
+        ...(skillComposition?.linkedHosts === undefined ? {} : { linkedHosts: skillComposition.linkedHosts }),
+        ...(inventoryDrift === undefined || inventoryDrift.status === "no-external-source" ? {} : { inventoryDrift }),
+        degraded: base.degraded || rosterSkipped.length > 0,
+    };
+    return {
+        state: "satisfied",
+        message: `${headline}\n${formatHubHealth(health)}`,
+        health,
+    };
+}
 /**
  * Read-only inventory validation: runs `gh repo view --json name` for each
  * repository id, batched. Tolerates a missing or failing `gh` by skipping with
@@ -656,29 +833,270 @@ export function checkInventoryEntries(host, directory) {
     }
     return { entries, skipped: false };
 }
-function withHealth(host, directory, headline, liveAdvisorVersion) {
-    const health = reportHubHealth(host, directory, liveAdvisorVersion);
-    return {
-        state: "satisfied",
-        message: `${headline}\n${formatHubHealth(health)}`,
-        health,
+function shouldRefreshConsumerAgents(existing) {
+    if (existing === null)
+        return true;
+    if (existing === CONSUMER_AGENTS_MD)
+        return false;
+    if (existing === LEGACY_CONSUMER_AGENTS_MD)
+        return true;
+    if (existing.includes("Run `npx @clossys/launcher` again to resume"))
+        return true;
+    return false;
+}
+function writeConsumerAgentsIfNeeded(host, directory) {
+    const existing = host.readText(join(directory, "AGENTS.md"));
+    if (!shouldRefreshConsumerAgents(existing))
+        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";
+function parseInventoryRepositoryId(id, hubOwner) {
+    const trimmed = id.trim();
+    if (trimmed === "")
+        return null;
+    if (trimmed.includes("/")) {
+        const slash = trimmed.indexOf("/");
+        const owner = trimmed.slice(0, slash);
+        const repository = trimmed.slice(slash + 1);
+        if (!OWNER.test(owner) || !REPO.test(repository))
+            return null;
+        return { owner, repository };
+    }
+    if (!REPO.test(trimmed))
+        return null;
+    return { owner: hubOwner, repository: trimmed };
+}
+function resolveSisterCloneTargets(host, hubDirectory, hubOwner) {
+    const parent = dirname(resolve(hubDirectory));
+    const hubResolved = resolve(hubDirectory);
+    const skipped = [];
+    const targets = [];
+    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;
+        const parsed = parseInventoryRepositoryId(id, hubOwner);
+        if (parsed === null) {
+            skipped.push({ inventoryId: id, note: "inventory id is not a valid repository slug" });
+            continue;
+        }
+        if (parsed.owner !== hubOwner) {
+            skipped.push({ inventoryId: id, note: "other account; not this roster" });
+            continue;
+        }
+        const candidate = join(parent, parsed.repository);
+        const candidateResolved = resolve(candidate);
+        if (candidateResolved === hubResolved)
+            continue;
+        if (!host.exists(candidate) || !host.isDirectory(candidate)) {
+            skipped.push({ inventoryId: id, note: CLONE_NOT_BESIDE_HUB_NOTE });
+            continue;
+        }
+        if (looksLikeFoundry(host, candidate)) {
+            skipped.push({ inventoryId: id, note: "foundry supplier tree; skills are not written here" });
+            continue;
+        }
+        const originResult = host.run("git", ["remote", "get-url", "origin"], { cwd: candidate });
+        const originUrl = originResult.status === 0 ? originResult.stdout.trim() : "";
+        const remote = originUrl === "" ? null : parseGitHubRemote(originUrl);
+        if (remote === null || remote.owner !== parsed.owner || remote.repository !== parsed.repository) {
+            skipped.push({ inventoryId: id, note: "git origin does not match inventory id" });
+            continue;
+        }
+        targets.push({ inventoryId: id, directory: candidate });
+    }
+    return { targets, skipped };
+}
+/**
+ * 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.
+ */
+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 });
+            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" });
+            continue;
+        }
+        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}` });
+        }
+        else {
+            outcomes.push({
+                inventoryId: skip.inventoryId,
+                result: "failed",
+                note: `gh repo clone exited ${result.status ?? "null"}: ${result.stderr.trim() || "no stderr"}`,
+            });
+        }
+    }
+    return outcomes;
+}
+function hubRosterId(host, hubDirectory, hubOwner, hubRepository) {
+    const document = readHub(host, hubDirectory);
+    if (document !== undefined)
+        return document.repository;
+    return `${hubOwner}/${hubRepository}`;
+}
+/**
+ * Regenerates the generated `README.md` at the root of `clossys/`: an index of which `clossys/<role>/`
+ * folders are active here, and what `.state/` holds. Written on every apply
+ * so it never drifts from what is actually on disk (#1171).
+ */
+function writeClossysReadme(host, directory) {
+    const root = join(directory, CLOSSYS_DIR_REL);
+    const roles = host
+        .isDirectory(root)
+        ? host
+            .readDir(root)
+            .filter((name) => name !== ".state" && name !== "README.md" && host.isDirectory(join(root, name)))
+            .sort((a, b) => a.localeCompare(b))
+        : [];
+    const hasBrief = host.exists(join(root, "brief.json"));
+    const lines = [
+        "# clossys/",
+        "",
+        "Generated by `@clossys/launcher`. This file is rewritten on every launcher",
+        `run to reflect what is active here; do not edit it by hand. Last generated: ${host.now()}.`,
+        "",
+        "## Engagement brief",
+        "",
+        ...(hasBrief
+            ? ["`clossys/brief.json` — why each role is staffed here, its goals, handoffs, and sequence (owner: @clossys/advisor)."]
+            : ["No engagement brief yet. `@clossys-advisor` writes `clossys/brief.json` once a plan is approved."]),
+        "",
+        "## Active roles",
+        "",
+        ...(roles.length === 0
+            ? ["No role folder is active here yet."]
+            : roles.map((role) => `- \`clossys/${role}/\` — @clossys-${role}`)),
+        "",
+        "## Machine state",
+        "",
+        "`clossys/.state/` holds machine files only: the hub marker, the inventory,",
+        "and the skills manifest. It is visible so it is easy to find, but it is not",
+        "a place a person edits by hand.",
+        "",
+    ];
+    writeSkeletonFile(host, directory, CLOSSYS_README_REL, lines.join("\n"));
+}
+/**
+ * Reads which coding-agent hosts already had skill discovery linked in
+ * `directory` BEFORE this call, then records that snapshot to
+ * `clossys/.state/hosts.json` (#1180). Deliberately called ahead of
+ * `composeSkills`, which unconditionally stamps discovery links for every
+ * host once it runs -- reading afterward would report "all hosts" on every
+ * apply and make the record meaningless.
+ */
+function recordLinkedHosts(host, directory) {
+    const linkedHosts = detectLinkedHosts(host, directory);
+    writeSkeletonFile(host, directory, HOSTS_REL, serializeHostRecord({ schemaVersion: 1, linkedHosts, recordedAt: host.now() }));
+    return linkedHosts;
+}
+function composeSkillRoster(host, hubDirectory, hubOwner, hubRepository, options) {
+    const composeOptions = {
+        launcherPackageRoot: options.launcherPackageRoot,
+        ...(options.skillCatalogueRoot === undefined ? {} : { skillCatalogueRoot: options.skillCatalogueRoot }),
+        ...(options.contractPath === undefined ? {} : { contractPath: options.contractPath }),
     };
+    const linkedHosts = recordLinkedHosts(host, hubDirectory);
+    const hubSkill = composeSkills(host, hubDirectory, composeOptions);
+    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 };
+}
+function finishHubApply(host, directory, headline, launcherPackageRoot, hubOwner, hubRepository, liveAdvisorVersion, skillCatalogueRoot, contractPath, liveLauncherVersion, migration) {
+    const skillComposition = composeSkillRoster(host, directory, hubOwner, hubRepository, {
+        launcherPackageRoot,
+        ...(skillCatalogueRoot === undefined ? {} : { skillCatalogueRoot }),
+        ...(contractPath === undefined ? {} : { contractPath }),
+    });
+    // #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);
 }
-/** Applies a create, resume, or adopt plan through the host. Resume does not write. */
-export function applyWorkspacePlan(host, plan, skeletonRoot) {
+/**
+ * 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.
+ */
+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`);
+    }
+    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. */
+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") {
         if (plan.clone) {
             requireZero(host.run("gh", ["repo", "clone", `${plan.owner}/${plan.repository}`, plan.directory]), "gh repo clone");
         }
-        return withHealth(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.`);
+        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);
     }
     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 withHealth(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.`, plan.advisorVersion);
+        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);
     }
     adoptHubFiles(host, skeletonRoot, plan);
-    return withHealth(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.`, plan.advisorVersion);
+    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);
+}
+export function launcherPackageRootFromModule(moduleUrl) {
+    return resolve(dirname(fileURLToPath(moduleUrl)), "..");
 }
 export function skeletonRootFromModule(moduleUrl) {
     return resolve(dirname(fileURLToPath(moduleUrl)), "..", "skeleton");