@clossys/launcher 0.3.0 → 0.4.0

package/src/types.ts

@@ -21,8 +21,18 @@ export interface WorkspaceHost {
   isDirectory(path: string): boolean;
   /** True when path exists and is a symlink (lstat; does not follow). Missing path is false. */
   isSymlink(path: string): boolean;
+  /** Decodes a file as UTF-8 text. Missing or unreadable is null. Not for contract documents: invalid bytes are silently replaced. */
   readText(path: string): string | null;
+  /**
+   * A file's exact bytes, never decoded. Missing or unreadable is null. Every
+   * inventory document is read this way and handed to the shared strict
+   * reader, so bytes that are not valid UTF-8 are refused rather than
+   * silently replaced with U+FFFD before anything checks them (#1179).
+   */
+  readBytes(path: string): Uint8Array | null;
   writeText(path: string, contents: string): void;
+  /** Writes these exact bytes, so a copied document stays byte-identical. */
+  writeBytes(path: string, contents: Uint8Array): void;
   mkdirp(path: string): void;
   /** Creates a relative symlink at linkPath pointing at relativeTarget (directory link). */
   symlink(relativeTarget: string, linkPath: string): void;
@@ -75,18 +85,29 @@ export interface SkillsManifestSummary {
 }
 
 export interface InventoryObservation {
-  readonly status: "missing" | "empty" | "populated";
+  /**
+   * "invalid" means a document was found but does not conform to the
+   * inventory schema (bad JSON, wrong shape, an unrecognized field, or a
+   * duplicate repository id) -- distinct from "empty" (a well-formed,
+   * zero-entry document) so a malformed document is reported, never
+   * silently treated as if it were merely empty.
+   */
+  readonly status: "missing" | "empty" | "populated" | "invalid";
   readonly count: number;
+  /** Present only when status is "invalid"; names the offending field. */
+  readonly reason?: string;
 }
 
-/** A package.json dependency bucket scanned for the advisor pin. */
+/** A package.json dependency bucket scanned for the hub engine pins. */
 export type DependencyBucket = "dependencies" | "devDependencies" | "optionalDependencies" | "peerDependencies";
 
-/** Staleness verdict for one pinned advisor version against the live registry version. */
+/** Staleness verdict for one pinned engine version against the live registry version. */
 export type PinGrade = "stale" | "current" | "indeterminate";
 
-/** One graded advisor pin in one dependency bucket. */
+/** One graded hub engine pin (`@clossys/advisor` or `@clossys/integrator`) in one dependency bucket. */
 export interface PinFinding {
+  /** The engine package this finding grades. */
+  readonly package: string;
   readonly bucket: DependencyBucket;
   readonly pinned: string;
   readonly grade: PinGrade;
@@ -107,20 +128,59 @@ export interface InventoryValidationReport {
   readonly note?: string;
 }
 
+/** Where one hub engine is pinned, by dependency bucket, and its live registry version when known. */
+export interface HubEnginePin {
+  readonly dependencies?: string;
+  readonly devDependencies?: string;
+  readonly optionalDependencies?: string;
+  readonly peerDependencies?: string;
+  readonly live?: string;
+}
+
+/** One change a run made to a hub engine pin in the hub's `package.json`. */
+export interface EnginePinChange {
+  /** The engine package: `@clossys/advisor` or `@clossys/integrator`. */
+  readonly package: string;
+  /** The version pinned before the run; absent when the engine was not pinned at all. */
+  readonly from?: string;
+  /** The version pinned in `devDependencies` after the run. */
+  readonly to: string;
+  /** The dependency bucket the pin was moved out of, when it was not in `devDependencies`. */
+  readonly movedFrom?: DependencyBucket;
+}
+
+/**
+ * The hub's lockfile does not resolve its engine pins yet (`kind`
+ * `engine-pins-changed-install-needed`): the hub's package manager install
+ * has to run, and `package.json` be committed together with the lockfile,
+ * before a frozen install (`npm ci`, `pnpm install --frozen-lockfile`,
+ * `yarn install --immutable`) accepts the hub again. Marks the report degraded.
+ */
+export interface EngineInstallFinding {
+  readonly kind: "engine-pins-changed-install-needed";
+  /** The lockfile found in the hub, e.g. `package-lock.json`. */
+  readonly lockfile: string;
+  /** The install command for that lockfile's package manager, e.g. `npm install`. */
+  readonly command: string;
+  /** The engines the lockfile does not resolve at their pinned version, or, for a lockfile Launcher does not read, the engines this run changed. */
+  readonly packages: readonly string[];
+  readonly note: string;
+}
+
 /** Read-only pin and inventory report after adopt or resume. Never uninstalls. */
 export interface HubHealthReport {
   readonly marker: "present" | "missing";
   readonly inventory: InventoryObservation;
-  readonly advisorPin: {
-    readonly dependencies?: string;
-    readonly devDependencies?: string;
-    readonly optionalDependencies?: string;
-    readonly peerDependencies?: string;
-    readonly live?: string;
-  };
+  readonly advisorPin: HubEnginePin;
+  readonly integratorPin: HubEnginePin;
+  /** True when either engine is pinned in more than one dependency bucket. */
   readonly dualPin: boolean;
   readonly extraClossys: readonly string[];
   readonly pinFindings: readonly PinFinding[];
+  /** Present when this run changed a hub engine pin in `package.json`: what changed, and the one next step (install, then commit `package.json` with its lockfile). */
+  readonly enginePins?: { readonly changed: readonly EnginePinChange[]; readonly nextStep: string };
+  /** Present when a lockfile in the hub does not resolve the engine pins yet; marks the report degraded. */
+  readonly installNeeded?: EngineInstallFinding;
   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[];
@@ -129,9 +189,33 @@ export interface HubHealthReport {
   readonly skillComposition?: {
     readonly composed: readonly string[];
     readonly skipped: readonly { readonly packageDir: string; readonly note: string }[];
+    /** The checkouts this run composed skills into: the hub. */
     readonly rosterTargets?: readonly string[];
-    readonly rosterSkipped?: readonly { readonly inventoryId: string; readonly note: string }[];
+    /**
+     * Each inventoried repository other than the hub, with what this run found
+     * for it (for example, a checkout beside the hub whose team arrives only
+     * once it is staffed in an approved plan, with that plan's setup pull
+     * request). Report-only: a hub run never writes into one, and no entry
+     * marks the report degraded. `inventoryId` is already a stored-inventory
+     * position label (e.g. `repositories[0] in the stored inventory`), never
+     * the raw id: this whole report is JSON-dumped into the apply message
+     * (see `formatHubHealth`'s `health:` line), so a raw id kept here would
+     * still reach that message even though no prose line built from it names
+     * the id either.
+     */
+    readonly siblings?: readonly { readonly inventoryId: string; readonly note: string }[];
     readonly retired?: readonly string[];
+    /**
+     * Composed skills in the hub left exactly as found because their on-disk
+     * content is not provably what Launcher last wrote (#1473). Any entry
+     * marks the report degraded.
+     */
+    readonly preserved?: readonly {
+      readonly packageDir: string;
+      readonly action: "rewrite" | "retire";
+      readonly path: string;
+      readonly note: string;
+    }[];
   };
   /** Present only on the run that performed the `.clossys/` -> `clossys/.state/` migration. */
   readonly migration?: { readonly status: "migrated"; readonly from: string; readonly to: string };
@@ -168,6 +252,8 @@ export interface WorkspaceObservation {
   readonly envOwner?: string;
   readonly remoteDefaultHub?: { readonly owner: string; readonly repository: string };
   readonly advisorVersion?: string;
+  /** The public `@clossys/integrator` registry version, read the same way as `advisorVersion`. */
+  readonly integratorVersion?: string;
   readonly ghAvailable: boolean;
   readonly gitAvailable: boolean;
 }
@@ -178,18 +264,50 @@ export interface WorkspacePlanCreate {
   readonly repository: string;
   readonly directory: string;
   readonly advisorVersion: string;
+  readonly integratorVersion: string;
 }
 
+/**
+ * What `launcher --repositories` does to the hub inventory (#1179): write
+ * the chosen repositories, or leave an inventory that already lists exactly
+ * those repositories as it is. Decided by `resolveChosenInventory()`.
+ */
+export type ChosenInventory =
+  | { readonly kind: "unchanged"; readonly count: number }
+  | {
+      readonly kind: "write";
+      /** The exact document text to write to `clossys/.state/inventory.json` (a generated hub path, not shipped in this package), already validated against the inventory contract. */
+      readonly document: string;
+      /** Repositories in the written document. */
+      readonly count: number;
+      /** Repositories the inventory listed before; 0 when there was none, it was empty, or it failed its contract. */
+      readonly previousCount: number;
+      /** Chosen ids the previous inventory did not list. Never put in a message text; see `addedPositions`. */
+      readonly added: readonly string[];
+      /** Previous ids the choice leaves out. Never put in a message text; see `removedPositions`. */
+      readonly removed: readonly string[];
+      /** Each `added` id's 0-based position in the `--repositories` argument, in the same order as `added`. What a message names instead of the id. */
+      readonly addedPositions: readonly number[];
+      /** Each `removed` id's 0-based position in the stored inventory's own `repositories` array, in the same order as `removed`. What a message names instead of the id. */
+      readonly removedPositions: readonly number[];
+      /** What the write replaces: nothing (no inventory, or an empty one), a differing valid inventory, or one that failed its contract. The last two happen only with an explicit replace approval. */
+      readonly replaced: "nothing" | "differing" | "invalid";
+    };
+
 export interface WorkspacePlanResume {
   readonly action: "resume";
   readonly owner: string;
   readonly repository: string;
   readonly directory: string;
   readonly clone: boolean;
-  /** Live registry Advisor version, when observeWorkspace could read one. Used only to grade health. */
+  /** Live registry Advisor version, when observeWorkspace could read one. Apply pins it in the hub and grades health against it. */
   readonly advisorVersion?: string;
+  /** Live registry Integrator version, when observeWorkspace could read one. Apply pins it in the hub and grades health against it. */
+  readonly integratorVersion?: string;
   /** Set when the hub marker was found only at the legacy `.clossys/` path; apply migrates it. */
   readonly migrateFrom?: "legacy";
+  /** Set by `--repositories`: the inventory apply writes before it composes skills, or confirms is unchanged. */
+  readonly chosenInventory?: ChosenInventory;
 }
 
 export interface WorkspacePlanAdopt {
@@ -198,10 +316,27 @@ export interface WorkspacePlanAdopt {
   readonly repository: string;
   readonly directory: string;
   readonly advisorVersion: string;
+  readonly integratorVersion: string;
   /** Absolute path of a populated inventory document to copy. Absent when cwd already has one. */
   readonly inventorySource?: string;
   /** Merged repository ids (on-disk first, then new ids from --inventory) written when both sources are populated. */
   readonly mergedInventoryIds?: readonly string[];
+  /**
+   * The merged entries themselves (each entry's `packages` kept), in the same order as `mergedInventoryIds` (#1334).
+   * Apply writes them when the plan carries no `mergedInventoryDocument`.
+   */
+  readonly mergedInventoryRepositories?: readonly { readonly id: string; readonly packages?: unknown }[];
+  /**
+   * The merged inventory document to write, when both sources are populated: every kept entry whole, its `packages`
+   * included, each repository once by Launcher's one identity rule (#1179) -- `mergedInventoryRepositories`, rendered.
+   * Preferred over `mergedInventoryRepositories` and `mergedInventoryIds`, which a hand-built plan may still carry
+   * without it; with ids alone, each id is written without packages.
+   */
+  readonly mergedInventoryDocument?: string;
+  /** Set when `inventorySource` is about to replace an on-disk inventory that failed schema validation, so the apply message can say it was replaced rather than merely written (#1334). */
+  readonly replacesInvalidInventory?: boolean;
+  /** Set by `--repositories`: the inventory apply writes, or confirms is unchanged (#1179). */
+  readonly chosenInventory?: ChosenInventory;
 }
 
 export type WorkspacePlan = WorkspacePlanCreate | WorkspacePlanResume | WorkspacePlanAdopt;

package/CHANGELOG.md

@@ -1,131 +0,0 @@
-# Changelog
-
-All notable changes to this package are documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.3.0] - 2026-09-22
-
-### Added
-
-- The product repository standard (#1215), recorded in this repository's own docs/contracts/product-repository-layout.json (not shipped in the published package) -- `apps/*`, workspace wiring, agent pointers, and CI, extending the consumer layout. `checkCloudSessionBootstrap()` verifies the three checks a cloud agent session (browser plus GitHub only, no local setup) needs before it can install and run the team in a product repository.
-- `launcher-doctor`: a read-only command that checks git, the GitHub command-line tool, sign-in, Node.js, and npm, and names the first missing prerequisite in plain language with the one next action to take -- never a dump of everything at once (#1220).
-- Adopts an existing repository inventory instead of writing a second, diverging one, when the hub marker declares an `externalInventory`. `reportInventoryDrift()` runs automatically on every `launcher` create, resume, or appoint and prints the result in hub health output -- external-only, launcher-only, and agreeing repository ids, all three even when one is empty -- instead of silently merging them (#1216).
-- `--clone-missing`, an explicit, non-default flag on `launcher` that clones inventoried repositories not yet sitting beside the hub (#1179), reversing the previous no-clone default for exactly this one approved action. Plain invocation is unchanged: still report-only by default.
-- Every `launcher` create, resume, or appoint records which coding-agent hosts a directory could already discover skills through -- read before that same run composes skills and stamps every host's discovery path -- into `clossys/.state/hosts.json`, for the hub and every sibling clone (#1180). Codex is detected by the presence of `.agents/skills` itself -- verified against Codex's own documentation, which reads repository skills from that path directly and needs no separate discovery symlink the way Claude Code and Cursor do.
-- Ships a per-host model profile (`model-profiles/<host>.json`) mapping the fixed reasoning tiers (`light` / `standard` / `deep`) to that host's current models, and reads `clossys/preferences.json`'s budget stance to resolve within it (#1219). Packages never name a model; only this profile does.
-- `launcher-apply-plan`: validates an approved `clossys/advisor/plan.json` and an `EngagementBrief`-shaped `clossys/brief.json` against the "Plan file contract" recorded on issue #1175, then writes the brief into a staffed repository byte-identically (#1178, #1176). Multi-repository orchestration (branch creation, exact package installs, Starter's caller workflow, opening one pull request per repository) is deferred -- see the package README's "Applying an approved plan" section for why.
-
-### Changed
-
-- `README.md`: documents the new commands and exports, and updates the "does not clone" line to describe the new explicit `--clone-missing` exception.
-
-### Fixed
-
-- `detectLinkedHosts()` (#1180) and `reportInventoryDrift()` (#1216) are now called from the real `launcher` command path (`applyWorkspacePlan`, via `composeSkillRoster` / `finishHubApply`) on every create, resume, and appoint, instead of existing only as library functions nothing called. Per independent review at f2a50de707f8682c6885592f2910425c2e5a0b5f: neither had a reachable call site, so no client-run command actually recorded a linked host or reported inventory drift despite the PR body and this changelog describing both as delivered behavior.
-
-## [0.2.0] - 2026-09-22
-
-### Added
-
-- Scaffolds one visible `clossys/` folder per repository: a generated `README.md` index of active roles at the root of `clossys/`, and `clossys/.state/` for machine files (hub marker, inventory, and the new skills manifest).
-- Writes `clossys/.state/skills.json` on every apply: each composed skill's source (`installed` or `catalogue`), version, and a content digest. The health report states how many composed skills are out of date against the live `@clossys/launcher` version and how many were retired this run; retirement removes only a skill this directory's own previous manifest listed, never one launcher did not write.
-- Packs the shared conversation contract at build time and injects it into every composed skill in place of that skill's own "how we work together" and "one question at a time" sections, at the same position. No package edit is needed for this to take effect.
-
-### Changed
-
-- Moves its own hub marker and inventory from the hidden `.clossys/` to the visible `clossys/.state/`; the packed skeleton template moves with it. Resume detects a hub still on the legacy path and migrates it automatically, reporting the move in the health report. A hub with a marker at both paths is graded `indeterminate` and launcher refuses rather than merging them silently.
-- Adds a `.gitignore` entry for generated run output under `clossys/**/.generated/`. Approved records, proof, and machine state are still committed, never ignored.
-
-## [0.1.8] - 2026-09-21
-
-### Added
-
-- Ships the packed Agent Skill in the tarball (`files` includes `skill`).
-
-### Fixed
-
-- Skill compose prefers each checkout's installed `@clossys/<package>/skill/SKILL.md` when present, then falls back to the packed catalogue or sibling source.
-- Apply marks hub health degraded when the skill roster skips inventoried targets; missing per-package catalogue sources remain notes only.
-
-## [0.1.7] - 2026-09-20
-
-### Changed
-
-- Packed skill catalogue now carries pre-auth fold gates, the exceptional-keep brief that ships with `@clossys/designer` (synthetic user, not the doer, the sealer, or a QA contractor), and expression-wave skills that treat 3 as the floor not done.
-
-## [0.1.6] - 2026-09-20
-
-### Changed
-
-- Appoint now pins live `@clossys/advisor` in `devDependencies` only. It relocates a pin left in another bucket and overwrites a frozen version. A dedicated `{owner}/workspace` hub is named `@owner/workspace`; an appointed product keeps its package name.
-- Observe always reads the public Advisor version, including when a pin already exists, so appoint can write the live pin and resume can grade it.
-- Health is degraded when Advisor is missing, dual-pinned, or present outside `devDependencies`, not only when the pin is older than live.
-- New-hub skeleton package name is `@owner/workspace`.
-- New-hub `AGENTS.md` tells the coding agent to speak to a founder in
-  ordinary sentences: where we are, what to do next, what we will not
-  do, and whether anything is saved to git. Machine identifiers stay
-  out of the default voice.
-
-### Fixed
-
-- Resume health now receives the live Advisor version from observe, so a stale or misplaced pin is visible on every resume instead of only after a fresh appoint.
-
-## [0.1.5] - 2026-09-20
-
-### Fixed
-
-- Discovery compose skips a `.claude/skills` or `.cursor/skills` path that is already a symlink so it cannot replace composed `SKILL.md`.
-
-## [0.1.4] - 2026-09-19
-
-### Added
-
-- Hub apply composes the full `clossys-*` skill tree under `.agents/skills/` on create, appoint, and resume, reading bodies from the packed skill catalogue (built at `npm run build` from each package's skill source) or from a sibling checkout. Missing sources are skipped with a health note; apply continues.
-- The same roster is composed into every inventoried repository clone beside the hub (resolved from the generated hub inventory and confirmed with `git remote get-url origin`); the health report lists targets and skipped ids. Sister checkouts get optional canned `AGENTS.md` only when missing or still the generated sister text.
-- Apply writes host discovery links under `.cursor/skills/` and `.claude/skills/` pointing at the composed skills in the hub and each resolved clone.
-- Packed Agent Skill `clossys-launcher` so a coding agent can be invoked as `@clossys-launcher`.
-
-### Changed
-
-- Resume refreshes composed skills and replaces stale generated `AGENTS.md` when it still tells founders to use `npx` to continue the conversation; customized `AGENTS.md` files are left alone.
-- Founder-facing hub guidance (`CONSUMER_AGENTS_MD`, skeleton README) now states the same `@clossys-*` team is available in every inventoried checkout; `@clossys-advisor` is the hiring check; `npx @clossys/launcher` refreshes voices on clones beside the hub.
-
-## [0.1.2] - 2026-09-19
-
-### Fixed
-
-- Appoint merges `--inventory` into a populated on-disk hub inventory instead of silently discarding the supplied document: repositories are unioned by id (on-disk order first, new ids appended in supplied order, first occurrence of an id wins) and the merged document is written to `.clossys/inventory.json` (that on-disk path does not ship with this package). The both-empty refusal is unchanged.
-- Resume with `--inventory` now refuses with "hub already appointed; edit `.clossys/inventory.json`" (that on-disk path does not ship with this package) instead of the misleading "--inventory is only valid when appointing".
-- Appoint refuses as `violated` when `CLOSSYS_OWNER` names a different account than the repository's github.com origin owner, naming both values; the marker is no longer written for the wrong account.
-- Appoint no longer requires a readable npm registry when the tree already pins `@clossys/advisor` in any dependency bucket (no new version would be needed); the indeterminate refusal only fires when a version is actually required.
-- Appoint refuses as `violated` when `git status --porcelain` is non-empty, before writing anything; when the origin is not on github.com the refusal names the remote host.
-
-### Added
-
-- Health report grades each Advisor pin against the live registry version (internal semver compare, no new dependencies): pin older than live is a `stale pin` finding and marks the report degraded; equal pins pass; unparseable comparisons are noted as indeterminate. Exit stays 0 on resume; adopt prints the same report.
-- Pin and extra-`@clossys/*` scans now cover `optionalDependencies` and `peerDependencies` in addition to `dependencies` and `devDependencies`.
-- `checkInventoryEntries()`: read-only validation of hub inventory repository ids through batched `gh repo view --json name`, marking unknown ids in the report and skipping with a note when `gh` is absent. Never mutates the inventory.
-- `launcher-check` forwards `cwd.hub`, so a captured existing-hub observation grades as resume instead of mis-grading as adopt.
-
-## [0.1.1] - 2026-09-19
-
-### Fixed
-
-- Appoint leaves an existing `@clossys/advisor` pin in whichever bucket it already occupies. It no longer dual-pins or overwrites a frozen version with the live registry version.
-- Appoint refuses when the generated hub inventory is missing or empty (packed template `skeleton/.clossys/inventory.json`; that generated path does not ship), unless `--inventory <path>` supplies a populated document. Create may still write an empty inventory. Resume does not invent one.
-
-### Added
-
-- Read-only health report after create, resume, and appoint: hub marker, inventory classification, Advisor pin location and version versus live, dual pin, extra `@clossys/*` names. Does not uninstall.
-
-## [0.1.0] - 2026-09-18
-
-### Added
-
-- `npx @clossys/launcher` as the single get-started command.
-- In-package hub skeleton (not a Foundry fork) copied into a GitHub repository.
-- Create a new `{owner}/workspace` hub, resume an existing hub, or adopt the current GitHub repository as the account hub.
-- Owner inference from `gh` and git remotes, with an interactive picker only when more than one GitHub owner is visible.
-- `launcher-check --input` grades a captured observation without creating a hub, so qualification can prove the 0/1/2 ternary.