@clossys/launcher 0.1.2 → 0.3.0

package/src/model-profile.ts

@@ -0,0 +1,148 @@
+// Model guidance (#1219, Launcher side). Owner decision: packages declare
+// WHAT a step demands (a reasoning tier), never model names. Three layers:
+//   1. Step demands -- each package's own loop matrix (#1197, not built here).
+//   2. Tier-to-model profile -- PER HOST, shipped by Launcher, dated and
+//      re-verified, so a model change reaches clients in one launcher
+//      release rather than a bump of every package.
+//   3. User preference -- cost-conscious / balanced / max-quality, asked
+//      once by Advisor, stored in clossys/preferences.json (Advisor's file
+//      to write; this module only reads it to resolve a tier to a model).
+//
+// Floors are hard where the verdict depends on it (Customer's keep):
+// resolveModelForTier never silently drops below a caller-supplied floor;
+// it reports belowFloor so the composed skill can say so plainly.
+
+import { join } from "node:path";
+
+export type ReasoningTier = "light" | "standard" | "deep";
+export type BudgetPreference = "cost-conscious" | "balanced" | "max-quality";
+export type SupportedHost = "claude-code" | "codex" | "cursor";
+
+export interface HostTierMapping {
+  /** The model this host runs for this tier under a "balanced" preference. */
+  readonly balanced: string;
+  /** Cheaper substitute under "cost-conscious", when one exists for this tier. Absent means "balanced" is already the floor. */
+  readonly costConscious?: string;
+  /** Stronger substitute under "max-quality", when one exists for this tier. */
+  readonly maxQuality?: string;
+}
+
+export interface HostModelProfile {
+  readonly schemaVersion: 1;
+  readonly host: SupportedHost;
+  /** ISO date this mapping was last verified against that host's real current models. */
+  readonly verifiedAt: string;
+  readonly tiers: Readonly<Record<ReasoningTier, HostTierMapping>>;
+}
+
+export interface PreferencesDocument {
+  readonly schemaVersion: 1;
+  readonly budget: BudgetPreference;
+}
+
+export interface ModelResolution {
+  readonly tier: ReasoningTier;
+  readonly host: SupportedHost;
+  readonly model: string;
+  /** True when a hard floor tier was requested but this host/preference combination could not clear it -- reported, never silently substituted. */
+  readonly belowFloor: boolean;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const TIER_ORDER: readonly ReasoningTier[] = ["light", "standard", "deep"];
+
+/** Parses clossys/preferences.json. Absent or malformed defaults to "balanced" -- a missing preference is not a floor violation. */
+export function parsePreferences(raw: string | null): PreferencesDocument {
+  if (raw !== null) {
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (
+        isRecord(parsed) &&
+        parsed.schemaVersion === 1 &&
+        (parsed.budget === "cost-conscious" || parsed.budget === "balanced" || parsed.budget === "max-quality")
+      ) {
+        return { schemaVersion: 1, budget: parsed.budget };
+      }
+    } catch {
+      /* falls through to the default below */
+    }
+  }
+  return { schemaVersion: 1, budget: "balanced" };
+}
+
+/**
+ * Resolves a step's demanded tier to a real model name for one host, under
+ * one budget preference, respecting an optional hard floor tier.
+ */
+export function resolveModelForTier(
+  profile: HostModelProfile,
+  tier: ReasoningTier,
+  budget: BudgetPreference,
+  floorTier?: ReasoningTier,
+): ModelResolution {
+  const mapping = profile.tiers[tier];
+  const model =
+    budget === "cost-conscious"
+      ? (mapping.costConscious ?? mapping.balanced)
+      : budget === "max-quality"
+        ? (mapping.maxQuality ?? mapping.balanced)
+        : mapping.balanced;
+  const belowFloor = floorTier !== undefined && TIER_ORDER.indexOf(tier) < TIER_ORDER.indexOf(floorTier);
+  return { tier, host: profile.host, model, belowFloor };
+}
+
+function isTierMapping(value: unknown): value is HostTierMapping {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.balanced === "string" &&
+    (record.costConscious === undefined || typeof record.costConscious === "string") &&
+    (record.maxQuality === undefined || typeof record.maxQuality === "string")
+  );
+}
+
+/**
+ * Reads a packed `model-profiles/<host>.json` file from the launcher
+ * package root. Returns undefined -- never throws, never guesses a
+ * fallback profile -- when the file is absent or malformed, matching this
+ * package's read-only, fail-closed pattern for every other packed
+ * artifact (manifest.ts's parseSkillManifest is the sibling to model this
+ * on).
+ */
+export function readHostModelProfile(
+  readText: (path: string) => string | null,
+  launcherPackageRoot: string,
+  host: SupportedHost,
+): HostModelProfile | undefined {
+  const raw = readText(join(launcherPackageRoot, "model-profiles", `${host}.json`));
+  if (raw === null) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    Array.isArray(parsed) ||
+    (parsed as Record<string, unknown>).schemaVersion !== 1 ||
+    (parsed as Record<string, unknown>).host !== host ||
+    typeof (parsed as Record<string, unknown>).verifiedAt !== "string"
+  ) {
+    return undefined;
+  }
+  const tiersRaw = (parsed as Record<string, unknown>).tiers;
+  if (typeof tiersRaw !== "object" || tiersRaw === null || Array.isArray(tiersRaw)) return undefined;
+  const tiers = tiersRaw as Record<string, unknown>;
+  if (!isTierMapping(tiers.light) || !isTierMapping(tiers.standard) || !isTierMapping(tiers.deep)) return undefined;
+  return {
+    schemaVersion: 1,
+    host,
+    verifiedAt: (parsed as { verifiedAt: string }).verifiedAt,
+    tiers: { light: tiers.light, standard: tiers.standard, deep: tiers.deep },
+  };
+}

package/src/product-repository.ts

@@ -0,0 +1,73 @@
+import { join } from "node:path";
+import type { WorkspaceHost } from "./types.js";
+
+/**
+ * One check from this repository's own docs/contracts/product-repository-layout.json `cloudSessionBootstrap` list (that contract file does not ship in the published package).
+ * Read-only: verifies a product repository has what a cloud agent session
+ * (browser plus GitHub only, no local setup) needs to install and run the
+ * team, without foundry's own heavy governance gates.
+ */
+export interface CloudBootstrapCheck {
+  readonly id: "package-manifest" | "agents-pointer" | "hub-marker";
+  readonly label: string;
+  readonly satisfied: boolean;
+  readonly note?: string;
+}
+
+export interface CloudBootstrapReport {
+  readonly schemaVersion: 1;
+  readonly checks: readonly CloudBootstrapCheck[];
+  readonly ready: boolean;
+}
+
+const PACKAGE_JSON_REL = "package.json";
+const PACKAGE_LOCK_REL = "package-lock.json";
+const AGENTS_MD_REL = "AGENTS.md";
+const HUB_MARKER_REL = join("clossys", ".state", "workspace.json");
+
+/**
+ * Runs the three product-repository-layout.json cloudSessionBootstrap checks
+ * against `directory`. Never mutates anything, never runs `npm ci` itself
+ * -- it checks that the manifest and lockfile are BOTH present, which is
+ * the precondition a real `npm ci` needs, not a substitute for running it.
+ */
+export function checkCloudSessionBootstrap(host: WorkspaceHost, directory: string): CloudBootstrapReport {
+  const hasManifest = host.exists(join(directory, PACKAGE_JSON_REL));
+  const hasLock = host.exists(join(directory, PACKAGE_LOCK_REL));
+  const manifestCheck: CloudBootstrapCheck = {
+    id: "package-manifest",
+    label: "package.json and package-lock.json are both present",
+    satisfied: hasManifest && hasLock,
+    ...(hasManifest && hasLock
+      ? {}
+      : {
+          note: !hasManifest && !hasLock
+            ? "Neither package.json nor package-lock.json exists yet."
+            : !hasManifest
+              ? "package-lock.json exists but package.json does not."
+              : "package.json exists but package-lock.json does not -- npm ci needs both.",
+        }),
+  };
+
+  const agentsRaw = host.readText(join(directory, AGENTS_MD_REL));
+  const agentsPointsAtClossys = agentsRaw !== null && agentsRaw.includes("clossys/");
+  const agentsCheck: CloudBootstrapCheck = {
+    id: "agents-pointer",
+    label: "AGENTS.md exists at the repository root and points at clossys/",
+    satisfied: agentsPointsAtClossys,
+    ...(agentsPointsAtClossys
+      ? {}
+      : { note: agentsRaw === null ? "AGENTS.md does not exist at the repository root." : "AGENTS.md exists but does not mention clossys/." }),
+  };
+
+  const hasHubMarker = host.exists(join(directory, HUB_MARKER_REL));
+  const markerCheck: CloudBootstrapCheck = {
+    id: "hub-marker",
+    label: "clossys/.state/workspace.json (the hub marker) is present",
+    satisfied: hasHubMarker,
+    ...(hasHubMarker ? {} : { note: "clossys/.state/workspace.json does not exist yet." }),
+  };
+
+  const checks = [manifestCheck, agentsCheck, markerCheck];
+  return { schemaVersion: 1, checks, ready: checks.every((check) => check.satisfied) };
+}

package/src/skills.ts

@@ -0,0 +1,225 @@
+import { dirname, join, resolve, sep } from "node:path";
+import { extractContractBlock, injectContract } from "./contract.js";
+import { parseSkillManifest, readInstalledVersion, serializeSkillManifest, sha256Hex } from "./manifest.js";
+import type { SkillManifestEntry, WorkspaceHost } from "./types.js";
+
+export interface SkillCompositionResult {
+  readonly composed: readonly string[];
+  readonly skipped: readonly { readonly packageDir: string; readonly note: string }[];
+  readonly rosterTargets?: readonly string[];
+  readonly rosterSkipped?: readonly { readonly inventoryId: string; readonly note: string }[];
+  /** Skills pruned this run: present in the directory's previous manifest, absent from this run's composed set. */
+  readonly retired: readonly string[];
+}
+
+export interface ComposeSkillsOptions {
+  readonly skillCatalogueRoot?: string;
+  readonly launcherPackageRoot: string;
+  /** Overrides where the packed conversation contract is read from (tests). */
+  readonly contractPath?: string;
+}
+
+export const DISCOVERY_PREFIXES = [".cursor/skills", ".claude/skills"] as const;
+const AGENTS_SKILLS_REL = join(".agents", "skills");
+export const SKILLS_MANIFEST_REL = join("clossys", ".state", "skills.json");
+
+function containedPath(root: string, relativePath: string): string {
+  const resolved = resolve(root, relativePath);
+  const prefix = root.endsWith(sep) ? root : `${root}${sep}`;
+  if (resolved !== root && !resolved.startsWith(prefix)) {
+    throw new Error(`refusing to write outside the workspace directory: ${relativePath}`);
+  }
+  return resolved;
+}
+
+function skillSourceCandidates(packageDir: string, options: ComposeSkillsOptions): string[] {
+  const paths: string[] = [];
+  if (options.skillCatalogueRoot) {
+    paths.push(join(options.skillCatalogueRoot, packageDir, "SKILL.md"));
+  }
+  paths.push(join(options.launcherPackageRoot, "skill-catalogue", packageDir, "SKILL.md"));
+  paths.push(join(options.launcherPackageRoot, "..", packageDir, "skill", "SKILL.md"));
+  return paths;
+}
+
+function installedSkillPath(composeTargetDirectory: string, packageDir: string): string {
+  return join(composeTargetDirectory, "node_modules", "@clossys", packageDir, "skill", "SKILL.md");
+}
+
+function readSkillBody(
+  host: WorkspaceHost,
+  packageDir: string,
+  options: ComposeSkillsOptions,
+  composeTargetDirectory: string,
+): { body: string; source: "installed" | "catalogue" } | null {
+  const installed = host.readText(installedSkillPath(composeTargetDirectory, packageDir));
+  if (installed !== null) return { body: installed, source: "installed" };
+  for (const path of skillSourceCandidates(packageDir, options)) {
+    const body = host.readText(path);
+    if (body !== null) return { body, source: "catalogue" };
+  }
+  return null;
+}
+
+function contractSourceCandidates(options: ComposeSkillsOptions): string[] {
+  const paths: string[] = [];
+  if (options.contractPath) paths.push(options.contractPath);
+  paths.push(join(options.launcherPackageRoot, "contracts", "conversation-contract.md"));
+  // Monorepo fallback so tests and dev runs work without a prior `npm run build` pack step.
+  paths.push(join(options.launcherPackageRoot, "..", "..", "docs", "contracts", "conversation-contract.md"));
+  return paths;
+}
+
+/** Reads and extracts the shared conversation contract block. Returns null when no source resolves. */
+function readContractBlock(host: WorkspaceHost, options: ComposeSkillsOptions): string | null {
+  for (const path of contractSourceCandidates(options)) {
+    const raw = host.readText(path);
+    if (raw === null) continue;
+    try {
+      return extractContractBlock(raw);
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function readLauncherVersion(host: WorkspaceHost, options: ComposeSkillsOptions): string | undefined {
+  const raw = host.readText(join(options.launcherPackageRoot, "package.json"));
+  if (raw === null) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && "version" in parsed) {
+      const version = (parsed as { version?: unknown }).version;
+      if (typeof version === "string" && version.trim() !== "") return version;
+    }
+  } catch {
+    /* unreadable manifest; no version */
+  }
+  return undefined;
+}
+
+/** Package directory names that have a resolvable skill source in the catalogue or monorepo. */
+export function listSkillPackageCandidates(host: WorkspaceHost, options: ComposeSkillsOptions): string[] {
+  const names = new Set<string>();
+  const considerRoot = (root: string | undefined): void => {
+    if (root === undefined || !host.isDirectory(root)) return;
+    for (const name of host.readDir(root)) {
+      if (name.startsWith(".")) continue;
+      const skillPath = join(root, name, "SKILL.md");
+      if (host.readText(skillPath) !== null) names.add(name);
+    }
+  };
+  considerRoot(options.skillCatalogueRoot);
+  considerRoot(join(options.launcherPackageRoot, "skill-catalogue"));
+  const packagesSibling = join(options.launcherPackageRoot, "..");
+  if (host.isDirectory(packagesSibling)) {
+    for (const name of host.readDir(packagesSibling)) {
+      if (name.startsWith(".")) continue;
+      const skillPath = join(packagesSibling, name, "skill", "SKILL.md");
+      if (host.readText(skillPath) !== null) names.add(name);
+    }
+  }
+  return [...names].sort((a, b) => a.localeCompare(b));
+}
+
+function writeAgentsSkill(host: WorkspaceHost, directory: string, packageDir: string, body: string): void {
+  const relativeDir = join(AGENTS_SKILLS_REL, `clossys-${packageDir}`);
+  const skillRel = join(relativeDir, "SKILL.md");
+  const target = containedPath(directory, skillRel);
+  host.mkdirp(dirname(target));
+  host.writeText(target, body.endsWith("\n") ? body : `${body}\n`);
+}
+
+function writeDiscoveryLink(host: WorkspaceHost, directory: string, packageDir: string, skillBody: string): void {
+  const agentsDirRel = join(AGENTS_SKILLS_REL, `clossys-${packageDir}`);
+  const linkTarget = join("..", "..", agentsDirRel);
+  for (const prefix of DISCOVERY_PREFIXES) {
+    const prefixPath = containedPath(directory, prefix);
+    // A directory-symlink onto `.agents/skills` already exposes every composed
+    // skill. Writing a nested `.claude/skills/clossys-<pkg>` link follows that
+    // symlink and replaces the just-written SKILL.md with a circular link.
+    if (host.isSymlink(prefixPath)) continue;
+    const linkRel = join(prefix, `clossys-${packageDir}`);
+    const linkPath = containedPath(directory, linkRel);
+    host.mkdirp(dirname(linkPath));
+    try {
+      host.symlink(linkTarget, linkPath);
+    } catch {
+      const fallbackDir = containedPath(directory, join(linkRel, "SKILL.md"));
+      host.mkdirp(dirname(fallbackDir));
+      host.writeText(fallbackDir, skillBody.endsWith("\n") ? skillBody : `${skillBody}\n`);
+    }
+  }
+}
+
+/** Removes a composed skill's `.agents/skills/` directory and its host discovery links. Missing paths are no-ops. */
+function removeComposedSkill(host: WorkspaceHost, directory: string, packageDir: string): void {
+  host.remove(containedPath(directory, join(AGENTS_SKILLS_REL, `clossys-${packageDir}`)));
+  for (const prefix of DISCOVERY_PREFIXES) {
+    const prefixPath = containedPath(directory, prefix);
+    if (host.isSymlink(prefixPath)) continue; // shared view onto .agents/skills; already handled above
+    host.remove(containedPath(directory, join(prefix, `clossys-${packageDir}`)));
+  }
+}
+
+/**
+ * Writes `.agents/skills/clossys-<pkg>/SKILL.md` and host discovery links for every
+ * catalogue package, with the shared conversation contract (#1182) injected in place
+ * of each skill's own `## How we work together` / `## One question at a time`
+ * sections. Missing sources are skipped with notes; the hub apply continues.
+ *
+ * Also writes `clossys/.state/skills.json` (#1183): source, version, and content
+ * digest per composed skill. A skill named in this directory's *previous* manifest
+ * but not composed this run is retired — its composed output is pruned and it is
+ * dropped from the new manifest. Never touches a skill this directory's manifest
+ * did not itself write.
+ */
+export function composeSkills(
+  host: WorkspaceHost,
+  directory: string,
+  options: ComposeSkillsOptions,
+): SkillCompositionResult {
+  const composed: string[] = [];
+  const skipped: { packageDir: string; note: string }[] = [];
+  const manifestEntries: SkillManifestEntry[] = [];
+  const contractBlock = readContractBlock(host, options);
+  const launcherVersion = readLauncherVersion(host, options);
+
+  for (const packageDir of listSkillPackageCandidates(host, options)) {
+    const found = readSkillBody(host, packageDir, options, directory);
+    if (found === null) {
+      skipped.push({ packageDir, note: "skill source missing at apply time" });
+      continue;
+    }
+    const body = contractBlock === null ? found.body : injectContract(found.body, contractBlock);
+    writeAgentsSkill(host, directory, packageDir, body);
+    writeDiscoveryLink(host, directory, packageDir, body);
+    composed.push(packageDir);
+    const version = found.source === "installed" ? readInstalledVersion(host, directory, packageDir) : launcherVersion;
+    manifestEntries.push({
+      name: packageDir,
+      source: found.source,
+      sha256: sha256Hex(body.endsWith("\n") ? body : `${body}\n`),
+      ...(version === undefined ? {} : { version }),
+    });
+  }
+
+  const previousManifest = parseSkillManifest(host.readText(join(directory, SKILLS_MANIFEST_REL)));
+  const composedSet = new Set(composed);
+  const retired: string[] = [];
+  for (const entry of previousManifest?.skills ?? []) {
+    if (composedSet.has(entry.name)) continue;
+    removeComposedSkill(host, directory, entry.name);
+    retired.push(entry.name);
+  }
+
+  const manifestPath = containedPath(directory, SKILLS_MANIFEST_REL);
+  host.mkdirp(dirname(manifestPath));
+  host.writeText(
+    manifestPath,
+    serializeSkillManifest({ schemaVersion: 1, generatedAt: host.now(), skills: manifestEntries }),
+  );
+
+  return { composed, skipped, retired };
+}

package/src/types.ts

@@ -1,3 +1,6 @@
+import type { DiscoveredHost } from "./hosts.js";
+import type { ExternalInventoryDeclaration, InventoryDriftReport } from "./inventory-adoption.js";
+
 /** Ternary retained by the installed CLI. */
 export type WorkspaceState = "satisfied" | "violated" | "indeterminate";
 
@@ -16,20 +19,59 @@ export interface WorkspaceHost {
   now(): string;
   exists(path: string): boolean;
   isDirectory(path: string): boolean;
+  /** True when path exists and is a symlink (lstat; does not follow). Missing path is false. */
+  isSymlink(path: string): boolean;
   readText(path: string): string | null;
   writeText(path: string, contents: string): void;
   mkdirp(path: string): void;
+  /** Creates a relative symlink at linkPath pointing at relativeTarget (directory link). */
+  symlink(relativeTarget: string, linkPath: string): void;
+  /** Recursively removes path. A missing path is a no-op, never a throw. */
+  remove(path: string): void;
   readDir(path: string): string[];
   run(command: string, args: readonly string[], options?: { cwd?: string }): CommandResult;
   prompt(message: string, choices: readonly string[]): string | null;
 }
 
-/** On-disk hub marker generated on the consumer hub. Packed template: skeleton/.clossys/workspace.json. */
+/** On-disk hub marker generated on the consumer hub. Packed template: skeleton/clossys/.state/workspace.json. */
 export interface HubDocument {
   readonly schemaVersion: 1;
   readonly kind: "account-hub";
   readonly owner: string;
   readonly repository: string;
+  /** Declares an existing external repository inventory as the source of truth (#1216). Hand-edited by the client; launcher never writes this field. */
+  readonly externalInventory?: ExternalInventoryDeclaration;
+}
+
+/**
+ * Where the hub marker was found relative to the `.clossys/` -> `clossys/.state/`
+ * migration (#1171): `clean` — only the current path. `legacy` — only the old
+ * `.clossys/` path; resume migrates it. `indeterminate` — both paths carry a
+ * parseable marker; launcher never merges them silently and refuses instead.
+ */
+export type HubMigrationState = "clean" | "legacy" | "indeterminate";
+
+/** One skill recorded in `clossys/.state/skills.json` (#1183). */
+export interface SkillManifestEntry {
+  readonly name: string;
+  readonly source: "installed" | "catalogue";
+  readonly version?: string;
+  readonly sha256: string;
+}
+
+/** The `clossys/.state/skills.json` document itself. */
+export interface SkillManifestDocument {
+  readonly schemaVersion: 1;
+  readonly generatedAt: string;
+  readonly skills: readonly SkillManifestEntry[];
+}
+
+/** Read-only freshness summary derived from the skills manifest for the health report. */
+export interface SkillsManifestSummary {
+  readonly status: "present" | "missing";
+  readonly total: number;
+  readonly stale: number;
+  readonly retired: number;
 }
 
 export interface InventoryObservation {
@@ -80,6 +122,31 @@ export interface HubHealthReport {
   readonly extraClossys: readonly string[];
   readonly pinFindings: readonly PinFinding[];
   readonly degraded: boolean;
+  /** Coding-agent hosts this apply found already linked for skill discovery here, recorded before compose ran (#1180). Always present after apply. */
+  readonly linkedHosts?: readonly DiscoveredHost[];
+  /** Present only when the hub marker declares an external inventory (#1216) and there is something to say about it (i.e. not "no-external-source"). */
+  readonly inventoryDrift?: InventoryDriftReport;
+  readonly skillComposition?: {
+    readonly composed: readonly string[];
+    readonly skipped: readonly { readonly packageDir: string; readonly note: string }[];
+    readonly rosterTargets?: readonly string[];
+    readonly rosterSkipped?: readonly { readonly inventoryId: string; readonly note: string }[];
+    readonly retired?: readonly string[];
+  };
+  /** Present only on the run that performed the `.clossys/` -> `clossys/.state/` migration. */
+  readonly migration?: { readonly status: "migrated"; readonly from: string; readonly to: string };
+  /** Freshness summary derived from `clossys/.state/skills.json`, when present. */
+  readonly skillsManifest?: SkillsManifestSummary;
+}
+
+/** Optional paths for skill composition during apply. */
+export interface ApplyWorkspaceOptions {
+  readonly skillCatalogueRoot?: string;
+  readonly launcherPackageRoot?: string;
+  /** Overrides where the packed conversation contract is read from (tests). */
+  readonly contractPath?: string;
+  /** Live registry `@clossys/launcher` version, used only to grade catalogue-sourced skill staleness. */
+  readonly liveLauncherVersion?: string;
 }
 
 export interface CwdObservation {
@@ -91,6 +158,8 @@ export interface CwdObservation {
   readonly hub?: HubDocument;
   readonly looksLikeFoundry: boolean;
   readonly inventory?: InventoryObservation;
+  /** Present only when a hub marker was found; absent means neither path has one. */
+  readonly hubMigration?: HubMigrationState;
 }
 
 export interface WorkspaceObservation {
@@ -117,6 +186,10 @@ export interface WorkspacePlanResume {
   readonly repository: string;
   readonly directory: string;
   readonly clone: boolean;
+  /** Live registry Advisor version, when observeWorkspace could read one. Used only to grade health. */
+  readonly advisorVersion?: string;
+  /** Set when the hub marker was found only at the legacy `.clossys/` path; apply migrates it. */
+  readonly migrateFrom?: "legacy";
 }
 
 export interface WorkspacePlanAdopt {