@clossys/launcher 0.1.5 → 0.3.1

package/src/doctor.ts

@@ -0,0 +1,145 @@
+// launcher doctor (#1220) -- read-only. Names each missing prerequisite in
+// plain language, one at a time, in the order a non-technical client
+// should fix them: git -> the GitHub command-line tool -> being signed in
+// -> Node.js -> npm. A missing coding agent is advisory only -- Launcher
+// cannot detect every host, and it is a one-time choice the client makes,
+// not a step to fix in sequence.
+
+import type { CommandResult } from "./types.js";
+
+export interface DoctorCheckHost {
+  run(command: string, args: readonly string[]): CommandResult;
+}
+
+export type DoctorStepId = "git" | "gh-cli" | "gh-auth" | "node" | "npm" | "coding-agent";
+
+export interface DoctorStepResult {
+  readonly id: DoctorStepId;
+  readonly label: string;
+  readonly satisfied: boolean;
+  /** Plain-language description of what is missing, present only when satisfied is false. */
+  readonly problem?: string;
+  /** The single next action, present only when satisfied is false. */
+  readonly nextAction?: string;
+  /** True for steps that inform but never block (e.g. coding-agent discovery). */
+  readonly advisory: boolean;
+}
+
+export interface DoctorReport {
+  readonly schemaVersion: 1;
+  readonly steps: readonly DoctorStepResult[];
+  /** The first unsatisfied non-advisory step, in order -- what the client should fix right now. */
+  readonly nextToFix?: DoctorStepResult;
+  readonly allSatisfied: boolean;
+}
+
+function ok(id: DoctorStepId, label: string, advisory = false): DoctorStepResult {
+  return { id, label, satisfied: true, advisory };
+}
+
+function missing(id: DoctorStepId, label: string, problem: string, nextAction: string, advisory = false): DoctorStepResult {
+  return { id, label, satisfied: false, problem, nextAction, advisory };
+}
+
+function commandSucceeds(host: DoctorCheckHost, command: string, args: readonly string[]): boolean {
+  try {
+    return host.run(command, args).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Runs every doctor check in the fix-in-this-order sequence. Never mutates anything. */
+export function runDoctorChecks(host: DoctorCheckHost): DoctorReport {
+  const steps: DoctorStepResult[] = [];
+
+  const hasGit = commandSucceeds(host, "git", ["--version"]);
+  steps.push(
+    hasGit
+      ? ok("git", "Git is installed")
+      : missing(
+          "git",
+          "Git is installed",
+          "Git is not installed on this computer. Launcher and your coding agent both need it to save and share work.",
+          "Install Git from https://git-scm.com/downloads, then run this command again.",
+        ),
+  );
+
+  const hasGh = commandSucceeds(host, "gh", ["--version"]);
+  steps.push(
+    hasGh
+      ? ok("gh-cli", "The GitHub command-line tool (gh) is installed")
+      : missing(
+          "gh-cli",
+          "The GitHub command-line tool (gh) is installed",
+          "The GitHub command-line tool is not installed. Launcher uses it to create and find your GitHub repositories.",
+          "Install it from https://cli.github.com, then run this command again.",
+        ),
+  );
+
+  const ghAuthed = hasGh && commandSucceeds(host, "gh", ["auth", "status"]);
+  steps.push(
+    !hasGh
+      ? missing(
+          "gh-auth",
+          "You are signed in to GitHub",
+          "This cannot be checked yet because the GitHub command-line tool is not installed.",
+          "Install the GitHub command-line tool first (see above), then run this command again.",
+        )
+      : ghAuthed
+        ? ok("gh-auth", "You are signed in to GitHub")
+        : missing(
+            "gh-auth",
+            "You are signed in to GitHub",
+            "You are not signed in to GitHub yet.",
+            "Run `gh auth login` and follow the prompts, then run this command again.",
+          ),
+  );
+
+  const hasNode = commandSucceeds(host, "node", ["--version"]);
+  steps.push(
+    hasNode
+      ? ok("node", "Node.js is installed")
+      : missing(
+          "node",
+          "Node.js is installed",
+          "Node.js is not installed. It is what runs the team's tools on this computer.",
+          "Install the current LTS release from https://nodejs.org, then run this command again.",
+        ),
+  );
+
+  const hasNpm = commandSucceeds(host, "npm", ["--version"]);
+  steps.push(
+    hasNpm
+      ? ok("npm", "npm is installed")
+      : missing(
+          "npm",
+          "npm is installed",
+          "npm is not installed. It comes with Node.js, so this is usually fixed by installing or reinstalling Node.js.",
+          "Install Node.js from https://nodejs.org (npm is included), then run this command again.",
+        ),
+  );
+
+  // Advisory only: never blocks doctor's overall verdict. A missing coding
+  // agent is not a step to fix in a particular order -- it is a one-time
+  // choice the client makes, and Launcher cannot detect every host.
+  steps.push(ok("coding-agent", "A coding agent is available to open this hub", true));
+
+  const firstUnsatisfied = steps.find((step) => !step.satisfied && !step.advisory);
+  return {
+    schemaVersion: 1,
+    steps,
+    ...(firstUnsatisfied === undefined ? {} : { nextToFix: firstUnsatisfied }),
+    allSatisfied: firstUnsatisfied === undefined,
+  };
+}
+
+/** Renders one step at a time, plain language, the way a non-technical client reads it. */
+export function renderDoctorReport(report: DoctorReport): string {
+  if (report.allSatisfied) {
+    return "Everything doctor checks is ready. Open this folder in your coding agent and talk to @clossys-advisor to get started.";
+  }
+  const step = report.nextToFix;
+  if (step === undefined) return "Everything doctor checks is ready.";
+  return `${step.label}: not yet.\n${step.problem}\n\nNext: ${step.nextAction}`;
+}

package/src/host.ts

@@ -69,6 +69,9 @@ export function createNodeHost(cwd = process.cwd(), env: NodeJS.ProcessEnv = pro
       if (existsSync(linkPath)) rmSync(linkPath, { recursive: true, force: true });
       symlinkSync(relativeTarget, linkPath, "dir");
     },
+    remove: (path) => {
+      rmSync(path, { recursive: true, force: true });
+    },
     readDir: (path) => readdirSync(path),
     run,
     prompt,

package/src/hosts.ts

@@ -0,0 +1,79 @@
+// Records which coding-agent host(s) this run linked skill discovery for
+// (#1180, Launcher side), so a consumer (Advisor's next-action phrasing)
+// can name the client's actual tool instead of guessing.
+//
+// Codex discovery verified 2026-09-22 (developers.openai.com/codex/skills,
+// developers.openai.com/codex/concepts/customization): Codex reads
+// repository skills directly from `.agents/skills` -- the SAME directory
+// skills.ts's AGENTS_SKILLS_REL already writes the real composed skill to.
+// It needs no separate discovery symlink the way Claude Code (.claude/skills)
+// and Cursor (.cursor/skills) do, so "codex" is detected by the presence of
+// `.agents/skills` itself, not a host-specific prefix.
+
+import { join } from "node:path";
+import type { WorkspaceHost } from "./types.js";
+
+export type DiscoveredHost = "claude-code" | "cursor" | "codex";
+
+export interface HostRecord {
+  readonly schemaVersion: 1;
+  /** Hosts whose discovery this directory currently carries. */
+  readonly linkedHosts: readonly DiscoveredHost[];
+  readonly recordedAt: string;
+}
+
+export const HOSTS_REL = join("clossys", ".state", "hosts.json");
+
+const AGENTS_SKILLS_REL = join(".agents", "skills");
+
+// Claude Code and Cursor need their own discovery symlink; Codex reads
+// .agents/skills directly (see module header) and is detected separately.
+const SYMLINK_DISCOVERY_PATHS: ReadonlyArray<{ host: DiscoveredHost; prefix: string }> = [
+  { host: "claude-code", prefix: ".claude/skills" },
+  { host: "cursor", prefix: ".cursor/skills" },
+];
+
+/** Read-only: which hosts can actually discover skills in this directory right now. */
+export function detectLinkedHosts(host: WorkspaceHost, directory: string): readonly DiscoveredHost[] {
+  const found: DiscoveredHost[] = [];
+  for (const { host: id, prefix } of SYMLINK_DISCOVERY_PATHS) {
+    if (host.isDirectory(join(directory, prefix)) || host.isSymlink(join(directory, prefix))) {
+      found.push(id);
+    }
+  }
+  if (host.isDirectory(join(directory, AGENTS_SKILLS_REL))) {
+    found.push("codex");
+  }
+  return found;
+}
+
+export function serializeHostRecord(record: HostRecord): string {
+  return `${JSON.stringify(record, null, 2)}\n`;
+}
+
+export function parseHostRecord(raw: string | null): HostRecord | undefined {
+  if (raw === null) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      !Array.isArray(parsed) &&
+      (parsed as Record<string, unknown>).schemaVersion === 1 &&
+      Array.isArray((parsed as Record<string, unknown>).linkedHosts)
+    ) {
+      const record = parsed as { linkedHosts: unknown[]; recordedAt: unknown };
+      const linkedHosts = record.linkedHosts.filter(
+        (item): item is DiscoveredHost => item === "claude-code" || item === "cursor" || item === "codex",
+      );
+      return {
+        schemaVersion: 1,
+        linkedHosts,
+        recordedAt: typeof record.recordedAt === "string" ? record.recordedAt : "",
+      };
+    }
+  } catch {
+    /* falls through */
+  }
+  return undefined;
+}

package/src/index.ts

@@ -2,6 +2,7 @@
 export {
   applyWorkspacePlan,
   checkInventoryEntries,
+  cloneMissingInventoryRepositories,
   formatHubHealth,
   hasAdvisorPin,
   inspectInventory,
@@ -11,11 +12,39 @@ export {
   parseGitHubRemote,
   planWorkspace,
   readInventoryRepositories,
+  readLiveLauncherVersion,
   reportHubHealth,
+  CLOSSYS_DIR_REL,
+  CLOSSYS_README_REL,
   DEFAULT_REPOSITORY_NAME,
+  LEGACY_STATE_DIR_REL,
+  LEGACY_WORKSPACE_INVENTORY_REL,
+  LEGACY_WORKSPACE_MARKER_REL,
+  STATE_DIR_REL,
   WORKSPACE_INVENTORY_REL,
   WORKSPACE_MARKER_REL,
 } from "./core.js";
+export type { CloneMissingOutcome } from "./core.js";
+export { runDoctorChecks, renderDoctorReport } from "./doctor.js";
+export { applyEngagementBrief, isPlanApproved, validateAdvisorPlan, validateEngagementBrief } from "./apply-plan.js";
+export type { AdvisorPlan, ApplyBriefResult, BlockerKind, EngagementBrief, EngagementBriefRole, PlanBlocker, PlanDecision, ValidationResult } from "./apply-plan.js";
+export type { DoctorCheckHost, DoctorReport, DoctorStepId, DoctorStepResult } from "./doctor.js";
+export { checkCloudSessionBootstrap } from "./product-repository.js";
+export type { CloudBootstrapCheck, CloudBootstrapReport } from "./product-repository.js";
+export { reportInventoryDrift } from "./inventory-adoption.js";
+export type { ExternalInventoryDeclaration, InventoryDriftReport } from "./inventory-adoption.js";
+export { detectLinkedHosts, parseHostRecord, serializeHostRecord, HOSTS_REL } from "./hosts.js";
+export type { DiscoveredHost, HostRecord } from "./hosts.js";
+export { parsePreferences, readHostModelProfile, resolveModelForTier } from "./model-profile.js";
+export type {
+  BudgetPreference,
+  HostModelProfile,
+  HostTierMapping,
+  ModelResolution,
+  PreferencesDocument,
+  ReasoningTier,
+  SupportedHost,
+} from "./model-profile.js";
 export type {
   ApplyWorkspaceOptions,
   CommandResult,
@@ -23,11 +52,15 @@ export type {
   DependencyBucket,
   HubDocument,
   HubHealthReport,
+  HubMigrationState,
   InventoryObservation,
   InventoryValidationEntry,
   InventoryValidationReport,
   PinFinding,
   PinGrade,
+  SkillManifestDocument,
+  SkillManifestEntry,
+  SkillsManifestSummary,
   WorkspaceApplyResult,
   WorkspaceDecision,
   WorkspaceHost,

package/src/inventory-adoption.ts

@@ -0,0 +1,85 @@
+// Adopt an existing repository inventory instead of creating a second one
+// (#1216). An account that already keeps a repository inventory in its own
+// control plane becomes the source of truth when the hub marker declares
+// it. Launcher writes only what that inventory lacks (a later apply step,
+// not this module) and reports drift instead of silently merging.
+
+import type { WorkspaceHost } from "./types.js";
+
+export interface ExternalInventoryDeclaration {
+  readonly path: string;
+  readonly shape: "foundry" | "custom";
+}
+
+export interface InventoryDriftReport {
+  readonly status: "no-external-source" | "reconciled" | "indeterminate";
+  readonly externalOnly: readonly string[];
+  readonly launcherOnly: readonly string[];
+  readonly agreeing: readonly string[];
+  readonly note?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Reads a foundry-shaped inventory document's repository ids. Malformed or missing is null, never []. */
+function readForeignIds(host: WorkspaceHost, path: string): readonly string[] | null {
+  const raw = host.readText(path);
+  if (raw === null) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed) || parsed.schemaVersion !== 1 || !Array.isArray(parsed.repositories)) return null;
+  const ids: string[] = [];
+  for (const entry of parsed.repositories) {
+    if (isRecord(entry) && typeof entry.id === "string" && entry.id.trim() !== "") ids.push(entry.id);
+  }
+  return ids;
+}
+
+/**
+ * Compares the declared external inventory against the launcher-written
+ * inventory at `directory/launcherInventoryRelPath`. Read-only -- callers
+ * decide whether and how to write the reconciled set, as an explicit,
+ * approved apply step (same #1045 pattern as clone-on-approval).
+ */
+export function reportInventoryDrift(
+  host: WorkspaceHost,
+  directory: string,
+  declaration: ExternalInventoryDeclaration | undefined,
+  launcherInventoryRelPath: string,
+): InventoryDriftReport {
+  if (declaration === undefined) {
+    return { status: "no-external-source", externalOnly: [], launcherOnly: [], agreeing: [] };
+  }
+  if (declaration.shape === "custom") {
+    return {
+      status: "indeterminate",
+      externalOnly: [],
+      launcherOnly: [],
+      agreeing: [],
+      note: `externalInventory at ${declaration.path} declares shape "custom"; launcher has no mapping for a non-foundry inventory shape yet and will not guess one. Reconcile by hand or file the mapping gap.`,
+    };
+  }
+  const externalIds = readForeignIds(host, declaration.path);
+  if (externalIds === null) {
+    return {
+      status: "indeterminate",
+      externalOnly: [],
+      launcherOnly: [],
+      agreeing: [],
+      note: `externalInventory at ${declaration.path} could not be read as a populated schemaVersion:1 inventory document.`,
+    };
+  }
+  const launcherIds = readForeignIds(host, `${directory}/${launcherInventoryRelPath}`) ?? [];
+  const externalSet = new Set(externalIds);
+  const launcherSet = new Set(launcherIds);
+  const externalOnly = externalIds.filter((id) => !launcherSet.has(id));
+  const launcherOnly = launcherIds.filter((id) => !externalSet.has(id));
+  const agreeing = externalIds.filter((id) => launcherSet.has(id));
+  return { status: "reconciled", externalOnly, launcherOnly, agreeing };
+}

package/src/manifest.ts

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import type { SkillManifestDocument, SkillManifestEntry, SkillsManifestSummary, WorkspaceHost } from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** sha256 hex digest of a skill's final composed content (post contract injection). */
+export function sha256Hex(content: string): string {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+/** Tiny semver-ish compare, duplicated from core.ts to keep this module dependency-free within the package. */
+function compareVersions(a: string, b: string): -1 | 0 | 1 | null {
+  const parse = (version: string): readonly number[] | null => {
+    const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)$/);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+  };
+  const left = parse(a);
+  const right = parse(b);
+  if (!left || !right) return null;
+  for (let index = 0; index < 3; index += 1) {
+    const l = left[index] ?? 0;
+    const r = right[index] ?? 0;
+    if (l < r) return -1;
+    if (l > r) return 1;
+  }
+  return 0;
+}
+
+/** Parses `clossys/.state/skills.json`. An unreadable or malformed document is treated as absent. */
+export function parseSkillManifest(raw: string | null): SkillManifestDocument | undefined {
+  if (raw === null) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(parsed) || parsed.schemaVersion !== 1 || !Array.isArray(parsed.skills)) return undefined;
+  const skills: SkillManifestEntry[] = [];
+  for (const entry of parsed.skills) {
+    if (!isRecord(entry)) continue;
+    const { name, source, sha256 } = entry;
+    if (typeof name !== "string" || name.trim() === "") continue;
+    if (source !== "installed" && source !== "catalogue") continue;
+    if (typeof sha256 !== "string" || sha256.trim() === "") continue;
+    skills.push({
+      name,
+      source,
+      sha256,
+      ...(typeof entry.version === "string" && entry.version.trim() !== "" ? { version: entry.version } : {}),
+    });
+  }
+  return {
+    schemaVersion: 1,
+    generatedAt: typeof parsed.generatedAt === "string" ? parsed.generatedAt : "",
+    skills,
+  };
+}
+
+export function serializeSkillManifest(document: SkillManifestDocument): string {
+  return `${JSON.stringify(document, null, 2)}\n`;
+}
+
+/**
+ * Freshness summary for the health report: "N skills out of date, M
+ * retired". `stale` counts catalogue-sourced entries whose recorded version
+ * is older than `liveLauncherVersion` (a client running an old launcher
+ * carries a catalogue only as fresh as that release, #1033) — unknown or
+ * unparseable versions are never counted stale. `retiredThisRun` is supplied
+ * by the composition step that just ran; a read-only inspection (no
+ * composition) reports 0 retired, which is correct — retirement is a
+ * this-run event, not a property of the manifest at rest.
+ */
+export function summarizeSkillsManifest(
+  manifest: SkillManifestDocument | undefined,
+  liveLauncherVersion: string | undefined,
+  retiredThisRun: readonly string[],
+): SkillsManifestSummary {
+  if (manifest === undefined) {
+    return { status: "missing", total: 0, stale: 0, retired: retiredThisRun.length };
+  }
+  const stale = manifest.skills.filter((entry) => {
+    if (entry.source !== "catalogue" || liveLauncherVersion === undefined || entry.version === undefined) return false;
+    return compareVersions(entry.version, liveLauncherVersion) === -1;
+  }).length;
+  return { status: "present", total: manifest.skills.length, stale, retired: retiredThisRun.length };
+}
+
+/** Reads `installed` version from `<composeTargetDirectory>/node_modules/@clossys/<pkg>/package.json`. */
+export function readInstalledVersion(host: WorkspaceHost, composeTargetDirectory: string, packageDir: string): string | undefined {
+  const raw = host.readText(join(composeTargetDirectory, "node_modules", "@clossys", packageDir, "package.json"));
+  if (raw === null) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (isRecord(parsed) && typeof parsed.version === "string" && parsed.version.trim() !== "") return parsed.version;
+  } catch {
+    /* unreadable manifest; no version */
+  }
+  return undefined;
+}

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 },
+  };
+}