@sous-io/sous 0.2.37 → 1.0.2

package/src/lib/repos/subscription-service.ts

@@ -1,3859 +0,0 @@
-/**
- * The subscription service: the workflow the consumer commands drive.
- *
- * Everything underneath it is a single-purpose part (a provider, the index
- * cache, the resolver, the trust layer, the store, the lockfile). This is the
- * one place that puts them in the right order, and the order is the design:
- *
- *   - Nothing is fetched from a repository before it is trusted, not even its
- *     index. `addRepo` runs the trust ceremony first and fetches second.
- *   - Resolution is iterative. Each round may turn up repositories a dependency
- *     needs that the project has not added; those go through one consolidated
- *     trust question and the round runs again.
- *   - A subscription is not finished until its questions are answered, so
- *     `subscribe` ends by asking for the variables its recipes publish.
- *   - Restoring never decides anything: it fetches exactly what the lockfile
- *     pins, which is what makes a fresh clone reproducible and prompt-free.
- *
- * Every collaborator is injectable, so a test can drive the whole workflow
- * against a local fixture repository without a network.
- */
-
-import fsp from "node:fs/promises";
-import path from "node:path";
-import semver from "semver";
-import { ConfigError, isConfigError } from "../errors.js";
-import { SOUS_VERSION, type ConfigContext, type Settings, type VarScope } from "../settings.js";
-import { CONFD_DIR_NAME } from "../config-discovery.js";
-import {
-  BULLET,
-  indent,
-  log,
-  palette,
-  warning,
-  wrapColumns,
-  wrapText,
-} from "../../utils/formatting.js";
-import { askChoice, askYesNo } from "../../utils/prompts.js";
-import { ensureStoreRootDirectory } from "../../utils/sous-directory.js";
-import { isInteractive, nonInteractiveError } from "../interactive.js";
-import {
-  applyProvidedAnswers,
-  askForMissing,
-  loadLadderContext,
-  planQuestions,
-  validateProvidedAnswers,
-  type AskReport,
-  type DefinedVariable,
-  type DefiningRecipe,
-  type LadderContext,
-  type PlannedVariable,
-  type ProvidedAnswer,
-} from "../vars/index.js";
-import type { IndexFile } from "./formats/index-file.js";
-import {
-  PROJECT_HOLDER,
-  type LockedRecipe,
-  type Lockfile,
-} from "./formats/lockfile.js";
-import type { RecipeManifest, VariableDefinition } from "./formats/recipe-manifest.js";
-import {
-  CachedIndexLookup,
-  RefPickArguments,
-  RefResolveArguments,
-  RefSource,
-  catalogRepoOfIndex,
-  describeRef,
-  formatRef,
-  isNamedRef,
-  locationFromUrl,
-  locationOf,
-  matchNames,
-  namespaceOf,
-  namespaceOfKey,
-  parseNamedRef,
-  rangeOf,
-  repoOf,
-  sharedRefPicker,
-  sharedRefResolver,
-  shortKey,
-  splitRecipeKey,
-  type CatalogRepo,
-  type NamedRef,
-  type RefKind,
-  type SousRef,
-} from "../../services/ref-resolver/index.js";
-import { describeIndexSearch } from "./ref-search.js";
-import {
-  PROJECT_REQUESTER,
-  proposeRepoName,
-  resolveRefs,
-  type MissingRepo,
-  type RefRequest,
-  type ResolvedRecipe,
-  type ResolverRepo,
-} from "./resolver.js";
-import {
-  LockService,
-  type LockDiff,
-  type LockRepoInput,
-  type RestoreReport,
-} from "./lock-service.js";
-import { TrustService, USER_ADDED_BY, type TrustedRepo } from "./trust.js";
-import {
-  SUBSCRIPTIONS_LAYER_FILENAME,
-  readManagedLayer,
-  removeManagedLayer,
-  updateManagedLayer,
-} from "./managed-layer.js";
-import {
-  builtInProviders,
-  createIndexCache,
-  requireProvider,
-  type IndexCache,
-  type ProviderOptions,
-  type ProviderId,
-  type RepoProvider,
-} from "./providers/index.js";
-import { normalizeRepoUrl } from "./providers/provider.js";
-import {
-  assertLocalRepoDirectory,
-  looksLikeLocalPath,
-  resolveRepoArgument,
-} from "./providers/local.js";
-import { RecipeStore } from "./store/recipe-store.js";
-import type { RecipeStoreLike, StoreKey } from "./store/contract.js";
-import { resolveStoreSettings } from "./store/settings.js";
-import {
-  NEWER_VERSION_CHECK_TIMEOUT_MS,
-  effectiveRangeForHolders,
-  findNewerInRange,
-  recordUpstreamCheck,
-  shouldCheckUpstream,
-  type NewerVersion,
-  withDeadline,
-} from "./freshness.js";
-import {
-  describeUpdateScope,
-  formatUpdatePlan,
-  isEmptyUpdate,
-  recipeInScope,
-  type UpdateScope,
-} from "./update-plan.js";
-import { REPO_NAME_PATTERN } from "./formats/patterns.js";
-import {
-  linkedPathFor,
-  readGlobalLinks,
-  readProjectLinks,
-  writeProjectLinks,
-} from "./links.js";
-import {
-  keysHeldBySubscription,
-  lockedClosure,
-  listLockedRecipes,
-  mapLinkedRecipes,
-  readRecipeManifestIn,
-} from "./locked-recipes.js";
-import { resolveStoreRoot } from "../sous-home.js";
-import {
-  packagedCoreIndexOverlay,
-  seedCoreRecipe,
-  type SeedCoreRecipeReport,
-} from "./seed.js";
-import { enabledRepos, enabledSubscriptions, isBuiltInEntry } from "./defaults.js";
-import {
-  CORE_NAMESPACE,
-  CORE_RECIPE_KEY,
-  OFFICIAL_REPO_IDENTITY,
-  packagedCoreRecipeDir,
-} from "./core-recipe.js";
-import { repoIdentity } from "./identity.js";
-import { buildRecipeTargets } from "./recipe-targets.js";
-import { resolveOutputPath } from "../markdown-compiler.js";
-import { hashDirectory } from "./store/hash.js";
-
-// --- Options and reports ------------------------------------------------------------------------
-
-/** How the subscription service is built. Every collaborator is injectable. */
-export type SubscriptionServiceOptions = {
-  /** The project's `.sous/` directory: lockfile, links map and env files. */
-  sousDir: string;
-  /** The project's `conf.d/` directory. Defaults to `<sousDir>/conf.d`. */
-  confDir?: string;
-  /** The merged project config. */
-  settings: Settings;
-  /** The environment to read; decides where the store is. Defaults to `process.env`. */
-  env?: NodeJS.ProcessEnv;
-  /**
-   * The real shell environment, snapshotted before the `.sous/` env files were
-   * injected. Used only to tell a shell-supplied answer from a file-supplied one.
-   */
-  shellEnv?: NodeJS.ProcessEnv;
-  /** Whether sous may ask questions. Defaults to whether both streams are a terminal. */
-  interactive?: boolean;
-  /** The recipe store. Defaults to the machine-wide one. */
-  store?: RecipeStoreLike;
-  /** The index cache. Defaults to one rooted at the store. */
-  indexCache?: IndexCache;
-  /** The trust layer. Defaults to one bound to this project. */
-  trust?: TrustService;
-  /** The lockfile service. Defaults to one bound to this project. */
-  lock?: LockService;
-  /** The providers to choose from. Defaults to the built-ins. */
-  providers?: RepoProvider[];
-  /** Options handed to every provider call. */
-  providerOptions?: ProviderOptions;
-  /** Where warnings go. Defaults to the console warning banner. */
-  warn?: (message: string) => void;
-  /** Where the plan and the resolution notices go. Defaults to the console. */
-  write?: (message: string) => void;
-  /** How a yes or no question is asked. Injected in tests. */
-  ask?: (message: string) => Promise<boolean>;
-  /** How a choice between candidate refs is asked. Injected in tests. */
-  choose?: (message: string, candidates: SousRef[]) => Promise<SousRef>;
-  /** The clock, so a recorded timestamp is predictable in tests. */
-  now?: () => Date;
-};
-
-/** What `addRepo` is asked to do. */
-export type AddRepoOptions = {
-  /** The repository's URL, or an absolute path for one on this machine. */
-  url: string;
-  /** The short name refs will use. Defaults to the last segment of the URL. */
-  name?: string;
-  /** The provider that handles it, when the URL does not give it away. */
-  provider?: ProviderId;
-  /** Acknowledge trust without being asked, for a run with no terminal. */
-  trust?: boolean;
-  /** Work out what would happen and report it, writing and fetching nothing. */
-  dryRun?: boolean;
-};
-
-/** What `addRepo` did. */
-export type AddRepoOutcome = {
-  /** The short name the repository was recorded under. */
-  name: string;
-  /** Where it lives, as recorded. */
-  url: string;
-  /** The provider that handles it. */
-  provider: ProviderId;
-  /** True when the project already trusted this exact repository. */
-  alreadyTrusted: boolean;
-  /** Every namespace its index declares, sorted. */
-  namespaces: string[];
-  /** How many recipes its index publishes. */
-  recipeCount: number;
-  /** True when nothing was written, because this was a dry run. */
-  dryRun: boolean;
-};
-
-/** What `subscribe` is asked to do. */
-export type SubscribeOptions = {
-  /** The ref to subscribe to: a namespace, or `namespace/recipe`, with an optional range. */
-  ref: string;
-  /** Let prerelease versions take part in range matching. */
-  prerelease?: boolean;
-  /** Prefer a newer in-range version over the locked one on every build. */
-  alwaysPull?: boolean;
-  /** Acknowledge trust for every repository this command adds, without being asked. */
-  trust?: boolean;
-  /** Accept the subscribe confirmation without being asked. */
-  yes?: boolean;
-  /** Take the first candidate when a one-word ref matched several things. */
-  acceptFirst?: boolean;
-  /**
-   * Answers supplied ahead of the questions, which are validated and stored
-   * before anything is asked. See `lib/vars/preanswers.ts`.
-   */
-  answers?: ProvidedAnswer[];
-  /** Work out what would happen and report it, writing and fetching nothing. */
-  dryRun?: boolean;
-};
-
-/** What `subscribe` did. */
-export type SubscribeOutcome = {
-  /** The ref that was installed, fully qualified, in its canonical written form. */
-  ref: string;
-  /** The ref as it was written, when a one-word ref had to be resolved first. */
-  resolvedFrom?: string;
-  /** The key the subscription was recorded under. */
-  key: string;
-  /** Every recipe version the resolution settled on. */
-  resolved: ResolvedRecipe[];
-  /** Repositories that had to be trusted along the way. */
-  trusted: string[];
-  /** What changed in the lockfile. */
-  diff: LockDiff;
-  /** What the variable questions produced, when they were asked. */
-  answers?: AskReport;
-  /**
-   * Every question these recipes would ask, and where each answer would go.
-   * Reported by a dry run, which is how a caller with no terminal finds out
-   * what to supply with `--answer`.
-   */
-  questions?: PlannedVariable[];
-  /**
-   * Recipes a dry run could not describe: their files are not on this machine,
-   * a dry run downloads nothing, and their repository's index does not record
-   * their questions. Their questions are unknown until they are installed.
-   */
-  unreadable?: string[];
-  /** Dependency cycles the resolver noticed, reported rather than treated as fatal. */
-  cycles: string[][];
-  /** True when nothing was written, because this was a dry run. */
-  dryRun: boolean;
-};
-
-/** What `previewSubscription` is asked about. */
-export type PreviewSubscriptionOptions = {
-  /** The indexes to resolve against, keyed by short name; the cached ones by default. */
-  indexes?: Map<string, IndexFile>;
-  /** Whether prerelease versions may take part in range matching. */
-  prerelease?: boolean;
-};
-
-/** What subscribing to a ref would install and ask, worked out without changing anything. */
-export type SubscriptionPreview = {
-  /** Every recipe version the subscription would install, sorted by key. */
-  resolved: ResolvedRecipe[];
-  /** Repositories the closure needs that the project does not trust yet. */
-  missingRepos: MissingRepo[];
-  /** Every question the closure would ask, and where each answer would go. */
-  questions: PlannedVariable[];
-  /** Recipes whose questions cannot be listed; see `SubscribeOutcome.unreadable`. */
-  unreadable: string[];
-  /** Dependency cycles the resolver noticed. */
-  cycles: string[][];
-};
-
-/** What `unsubscribe` is asked to do. */
-export type UnsubscribeOptions = {
-  /** The ref to unsubscribe from. */
-  ref: string;
-  /** Work out what would happen and report it, writing nothing. */
-  dryRun?: boolean;
-};
-
-/** What `unsubscribe` did. */
-export type UnsubscribeOutcome = {
-  /** The key the subscription was recorded under. */
-  key: string;
-  /** What changed in the lockfile. */
-  diff: LockDiff;
-  /** Recipes that stayed because something else still holds them, with who holds them. */
-  stayed: Array<{ key: string; heldBy: string[] }>;
-  /**
-   * True when the subscription was one sous provides itself, so it was switched
-   * off with an `enabled: false` entry rather than deleted. The entry sous
-   * provides comes back on every run; only a recorded opt-out outlives it.
-   */
-  optedOut: boolean;
-  /** True when nothing was written, because this was a dry run. */
-  dryRun: boolean;
-};
-
-/** What `removeRepo` is asked to do. */
-export type RemoveRepoOptions = {
-  /** The repository's short name, as the project records it. */
-  name: string;
-  /** Accept the removal without being asked. */
-  yes?: boolean;
-  /** Work out what would happen and report it, writing nothing. */
-  dryRun?: boolean;
-  /**
-   * The resolved settings scope, used to work out which output files the
-   * removed recipes wrote. Without it a `recipes.skills.outputs` destination holding a
-   * `${var}` cannot be resolved, and the file list is left out of the report.
-   */
-  scope?: VarScope;
-};
-
-/** What `removeRepo` did, or would do on a dry run. */
-export type RemoveRepoOutcome = {
-  /** The repository's short name. */
-  name: string;
-  /** Where it lives, as the entry recorded it. */
-  url: string;
-  /**
-   * True when the repository is one sous provides itself, so it was switched
-   * off with an `enabled: false` entry rather than deleted. The entry sous
-   * provides comes back on every run; only a recorded opt-out outlives it.
-   */
-  optedOut: boolean;
-  /** The subscriptions that were removed because they resolve into it. */
-  subscriptions: string[];
-  /**
-   * Subscriptions that resolve into it but are written in the project's own
-   * config, which sous never edits. They stay, and are named so the person
-   * removing the repository knows to deal with them.
-   */
-  keptSubscriptions: string[];
-  /** The locked recipes that were released, because nothing else held them. */
-  removedRecipes: string[];
-  /** Recipes that stayed because something else still holds them, with who holds them. */
-  stayed: Array<{ key: string; heldBy: string[] }>;
-  /** The output files the removed recipes compiled, which the next build prunes. */
-  outputs: string[];
-  /** What changed in the lockfile. */
-  diff: LockDiff;
-  /** The linked checkout that pointed at the repository, when there was one. */
-  linkedPath?: string;
-  /**
-   * True when that link is the machine-wide one, which other projects on this
-   * machine share, so it was left exactly as it was.
-   */
-  linkIsGlobal: boolean;
-  /** True when nothing was written, because this was a dry run. */
-  dryRun: boolean;
-};
-
-/** One row of the subscription listing: what a project subscribes to, and why. */
-export type SubscriptionListing = {
-  /** The ref key: a bare namespace, or `namespace/recipe`. */
-  key: string;
-  /** The version range the subscription resolves within, when one was written. */
-  range: string | undefined;
-  /** False when the entry is switched off with `enabled: false`. */
-  enabled: boolean;
-  /** What the entry recorded about who wanted it, when it recorded anything. */
-  addedBy: string | undefined;
-  /** Every recipe the lockfile pins because of this subscription, sorted by key. */
-  pinned: Array<{ key: string; version: string }>;
-};
-
-/** What bringing the lockfile in line with the declared subscriptions produced. */
-export type SubscriptionSyncReport = {
-  /** The subscriptions that had to be resolved, by ref key. */
-  resolved: string[];
-  /** Recipes the lockfile did not pin before and pins now. */
-  added: Array<{ key: string; version: string }>;
-  /** Recipes whose pinned version moved to satisfy a subscription's range. */
-  moved: Array<{ key: string; from: string; to: string }>;
-  /** Subscriptions that could not be resolved, each with a plain-language reason. */
-  failed: Array<{ key: string; reason: string }>;
-};
-
-/** What an upstream check found. */
-export type UpstreamCheckReport = {
-  /** Repositories that were actually asked. */
-  checked: string[];
-  /** Recipes moved to a newer in-range version. */
-  updated: Array<{ key: string; from: string; to: string }>;
-  /** Repositories whose check failed; the last good answer still stands. */
-  failed: Array<{ repo: string; reason: string }>;
-  /**
-   * Locked recipes with a newer version inside the range their holders
-   * declared, in a repository that does not prefer newer versions. Nothing
-   * moved; this is only what a build tells the person running it.
-   */
-  newer: Array<{ key: string; repo: string; from: string; to: string }>;
-  /**
-   * Repositories sous looked at only to find newer versions, whose look failed
-   * or ran out of time. Kept quiet: the cached index answered instead.
-   */
-  unchecked: Array<{ repo: string; reason: string }>;
-};
-
-/** What `update` is asked to do. */
-export type UpdateOptions = {
-  /**
-   * What to update: a repository, a namespace or a recipe, written at any level
-   * of qualification and resolved through `src/services/ref-resolver/`. Left out, every
-   * subscription is updated.
-   */
-  ref?: string;
-  /**
-   * A repository short name the caller has already settled, which narrows the
-   * update exactly as a reference naming that repository would. `sous repo
-   * unlink --update` passes this; it is never combined with `ref`.
-   */
-  repo?: string;
-  /** Accept the plan, and trust any repository a newer version needs, without being asked. */
-  yes?: boolean;
-  /** Take the first candidate when the reference matched several things. */
-  acceptFirst?: boolean;
-  /** Answers supplied ahead of the questions the new versions ask. */
-  answers?: ProvidedAnswer[];
-  /** Work out and print the plan, writing nothing and downloading no recipe. */
-  dryRun?: boolean;
-};
-
-/** What `update` did, or would do on a dry run. */
-export type UpdateOutcome = {
-  /** What the update covered. */
-  scope: UpdateScope;
-  /** What changed in the lockfile. */
-  diff: LockDiff;
-  /** True when nothing needed moving, so nothing was asked and nothing written. */
-  nothingToUpdate: boolean;
-  /** Repositories whose index could not be fetched; their pins stayed. */
-  unreachable: Array<{ repo: string; reason: string }>;
-  /** Subscriptions that could not be resolved; their pins stayed. */
-  failed: Array<{ key: string; reason: string }>;
-  /** Linked repositories whose pins moved. */
-  linked: string[];
-  /** Repositories trusted along the way. */
-  trusted: string[];
-  /** What the variable questions produced, when any were asked. */
-  answers?: AskReport;
-  /** Dependency cycles the resolver noticed. */
-  cycles: string[][];
-  /** True when nothing was written, because this was a dry run. */
-  dryRun: boolean;
-};
-
-/** What looking for newer published versions of one repository's pins found. */
-export type NewerVersionsReport =
-  | {
-      /** The index was fetched and compared. */
-      checked: true;
-      /** Every pin with a newer published version its range allows, by key. */
-      newer: NewerVersion[];
-    }
-  | {
-      /** The index could not be fetched in time, so nothing is known. */
-      checked: false;
-      /** Why not, as a sentence. */
-      reason: string;
-    };
-
-// --- The service --------------------------------------------------------------------------------
-
-/** Adds repositories, subscribes to recipes, and keeps the store and lockfile honest. */
-export class SubscriptionService {
-  private readonly sousDir: string;
-
-  private readonly confDir: string;
-
-  private readonly settings: Settings;
-
-  private readonly env: NodeJS.ProcessEnv;
-
-  private readonly shellEnv: NodeJS.ProcessEnv;
-
-  private readonly interactive: boolean;
-
-  private readonly providers: RepoProvider[];
-
-  private readonly providerOptions: ProviderOptions;
-
-  private readonly warn: (message: string) => void;
-
-  private readonly write: (message: string) => void;
-
-  private readonly ask: (message: string) => Promise<boolean>;
-
-  private readonly choose: (message: string, candidates: SousRef[]) => Promise<SousRef>;
-
-  private readonly now: () => Date;
-
-  private readonly storeInstance: RecipeStoreLike;
-
-  private readonly indexCache: IndexCache;
-
-  private readonly trust: TrustService;
-
-  private readonly lock: LockService;
-
-  /**
-   * Canonical identities already worked out, keyed by the provider and URL they
-   * came from. Canonicalizing is pure, so it is worth doing once per run.
-   */
-  private readonly identityCache = new Map<string, string>();
-
-  /**
-   * What seeding the packaged core recipe did, once it has been done. Seeding is
-   * idempotent but not free (it verifies the store entry against its content
-   * hash), so one service instance does it at most once.
-   */
-  private seedReport: SeedCoreRecipeReport | undefined;
-
-  /**
-   * Where each locked recipe's files are, keyed by recipe key, once it has been
-   * looked up. Deriving the range a `depends`-held recipe may move within asks
-   * for this once per lockfile entry, and the answer does not change during a
-   * command.
-   */
-  private lockedDirectories: Record<string, string> | undefined;
-
-  /**
-   * Every trusted repository's index, once it has been loaded. Working out what
-   * a one-word ref meant and describing what a subscription will do both read
-   * it, within one command, and an index does not change mid-command.
-   */
-  private indexesSnapshot: Map<string, IndexFile> | undefined;
-
-  /**
-   * @param options - The project's directories, its config, and any collaborator to override.
-   */
-  constructor(options: SubscriptionServiceOptions) {
-    this.sousDir = options.sousDir;
-    this.confDir = options.confDir ?? path.join(options.sousDir, CONFD_DIR_NAME);
-    this.settings = options.settings;
-    this.env = options.env ?? process.env;
-    this.shellEnv = options.shellEnv ?? this.env;
-    this.interactive = options.interactive ?? isInteractive();
-    this.providers = options.providers ?? builtInProviders();
-    this.providerOptions = options.providerOptions ?? {};
-    this.warn = options.warn ?? warning;
-    this.write = options.write ?? ((message: string) => log(message));
-    this.ask = options.ask ?? ((message: string) => askYesNo(message));
-    this.choose =
-      options.choose ??
-      ((message, candidates) =>
-        askChoice(
-          message,
-          candidates.map((candidate) => ({
-            name: describeRef(candidate),
-            value: candidate,
-          }))
-        ));
-    this.now = options.now ?? (() => new Date());
-
-    this.storeInstance =
-      options.store ??
-      new RecipeStore({ root: resolveStoreRoot(this.env), onWarning: this.warn });
-    this.indexCache =
-      options.indexCache ??
-      createIndexCache({
-        storeRoot: this.storeInstance.root,
-        resolveProvider: (url, providerId) =>
-          requireProvider(url, providerId, this.providers),
-        providerOptions: this.providerOptions,
-        warn: this.warn,
-        now: this.now,
-        // Every cache a command builds knows the packaged core version from the
-        // start, so a command that never seeds (a lockfile rebuild, a browsing
-        // command) resolves and lists exactly what a build does. Seeding
-        // replaces this with an overlay carrying the seeded entry's own hash.
-        overlay: packagedCoreIndexOverlay({ version: SOUS_VERSION, warn: this.warn }),
-      });
-    this.trust =
-      options.trust ??
-      new TrustService({
-        sousDir: this.sousDir,
-        confDir: this.confDir,
-        settings: this.settings,
-        interactive: this.interactive,
-        // The trust question is one of this service's questions, so it is asked
-        // and printed through the same seams as the rest of them.
-        ask: this.ask,
-        write: this.write,
-        now: this.now,
-      });
-    this.lock = options.lock ?? new LockService(this.sousDir);
-  }
-
-  /** The recipe store this service fills and reads. */
-  get store(): RecipeStoreLike {
-    return this.storeInstance;
-  }
-
-  /** The lockfile service this project uses. */
-  get lockService(): LockService {
-    return this.lock;
-  }
-
-  /** The index cache, for a command that wants to read a cached index without fetching. */
-  get indexes(): IndexCache {
-    return this.indexCache;
-  }
-
-  /**
-   * The cached index of one added repository, or undefined when nothing has
-   * been fetched from it yet. Nothing is downloaded. Callers name the
-   * repository the way the project does, by its short name; the cache itself is
-   * keyed by identity, and this is what translates between the two.
-   *
-   * @param name - The repository's short name.
-   */
-  cachedIndex(name: string): IndexFile | undefined {
-    const identity = this.identityForRepo(name);
-    return identity === undefined ? undefined : this.indexCache.readCached(identity);
-  }
-
-  /**
-   * Every trusted repository as a reference searches it, read from the cached
-   * indexes alone: what it publishes, where each recipe lives, and its
-   * canonical identity, so a reference written as a location finds it whatever
-   * this project calls it. A repository whose index has never been fetched can
-   * still be named, just not searched inside.
-   */
-  cachedReferenceRepos(): CatalogRepo[] {
-    const repos = this.resolverRepos();
-    return Object.keys(repos).map((name) => {
-      const { url } = repos[name]!;
-      const index = this.cachedIndex(name);
-      const location = locationFromUrl(url, this.providers);
-      const known = { name, ...(location === undefined ? {} : { location }) };
-      return index === undefined
-        ? { ...known, namespaces: [], recipes: [] }
-        : catalogRepoOfIndex(index, known);
-    });
-  }
-
-  // --- Repository identity ----------------------------------------------------------------------
-
-  /**
-   * The canonical identity of a repository at a URL: what the machine-wide
-   * store and the index cache file it under. Canonicalizing runs a provider's
-   * URL parser, so the answers are remembered for the life of the service.
-   *
-   * @param url - Where the repository lives.
-   * @param providerId - The provider the repository entry names, when it names one.
-   */
-  private identityOf(url: string, providerId?: string): string {
-    const cacheKey = `${providerId ?? ""}|${url}`;
-    const known = this.identityCache.get(cacheKey);
-    if (known !== undefined) return known;
-
-    const provider = requireProvider(url, providerId, this.providers);
-    const identity = repoIdentity(provider.canonicalize(url));
-    this.identityCache.set(cacheKey, identity);
-    return identity;
-  }
-
-  /**
-   * The canonical identity of an added repository, by the short name this
-   * project calls it. The lockfile is consulted second, so a repository that
-   * has been removed from the config can still be located while its recipes are
-   * being cleaned up.
-   *
-   * @param name - The repository's short name.
-   * @param lock - The lockfile, when the caller has already read it.
-   */
-  identityForRepo(name: string, lock?: Lockfile): string | undefined {
-    const entry = this.currentRepos()[name];
-    if (entry?.url !== undefined) return this.identityOf(entry.url, entry.provider);
-
-    const locked = (lock ?? this.lock.read()).repos[name];
-    if (locked === undefined) return undefined;
-    return locked.identity;
-  }
-
-  // --- Adding a repository ----------------------------------------------------------------------
-
-  /**
-   * Adds a repository, which is the same thing as trusting it, and then fetches
-   * exactly one file from it: its index. Nothing is downloaded before the trust
-   * question is answered.
-   *
-   * A path is normalized before anything else happens: `~` is expanded and a
-   * relative path is resolved against the working directory, so what gets
-   * stored is always absolute (a repository on this machine is machine-specific
-   * whichever way it was typed). A path that is not a repository is reported as
-   * a path mistake, naming what was typed and where sous looked, rather than as
-   * a provider that could not be found.
-   *
-   * @param options - The URL, an optional short name and provider, and the trust flag.
-   */
-  async addRepo(options: AddRepoOptions): Promise<AddRepoOutcome> {
-    const typed = options.url.trim();
-    const url = resolveRepoArgument(typed);
-    if (looksLikeLocalPath(typed)) assertLocalRepoDirectory(typed, url);
-    const provider = requireProvider(url, options.provider, this.providers);
-    const canonical = provider.canonicalize(url);
-    const name = options.name ?? canonical.name;
-
-    if (!REPO_NAME_PATTERN.test(name)) {
-      throw new ConfigError(
-        `'${name}' is not a usable short name for a repository.\n` +
-          `  A short name is lowercase kebab-case: a letter, then letters, digits or ` +
-          `hyphens. It is what refs use as the 'repo:' qualifier.\n` +
-          `  Choose one with '--name', for example ` +
-          `'sous repo add ${url} --name my-recipes'.`
-      );
-    }
-
-    const existing = this.currentRepos()[name];
-    const alreadyTrusted =
-      existing !== undefined && normalizeRepoUrl(existing.url) === normalizeRepoUrl(url);
-
-    if (existing !== undefined && !alreadyTrusted) {
-      throw new ConfigError(
-        `This project already has a repository called '${name}', and it is a different one.\n` +
-          `  Already added: ${existing.url}\n` +
-          `  Being added:   ${url}\n` +
-          `  Give this one a name of its own with '--name', for example ` +
-          `'sous repo add ${url} --name ${name}-2'.`
-      );
-    }
-
-    if (options.dryRun === true) {
-      return {
-        name,
-        url,
-        provider: provider.id,
-        alreadyTrusted,
-        namespaces: [],
-        recipeCount: 0,
-        dryRun: true,
-      };
-    }
-
-    // Trust first, fetch second. This is the last gate before a repository's
-    // recipes can put files (and scripts) on this machine.
-    if (!alreadyTrusted) {
-      await this.trust.confirmTrust(
-        [
-          {
-            name,
-            url,
-            requiredBy: [{ ref: name, requestedBy: PROJECT_REQUESTER }],
-          },
-        ],
-        {
-          interactive: this.interactive,
-          ...(options.trust === undefined ? {} : { trustFlag: options.trust }),
-        }
-      );
-    }
-
-    // Written again even when confirmTrust already wrote it, so the entry records
-    // that a person added this repository deliberately rather than a dependency
-    // having dragged it in.
-    this.trust.addRepo({
-      name,
-      url,
-      ...(options.provider === undefined ? {} : { provider: options.provider }),
-      addedBy: USER_ADDED_BY,
-    });
-
-    const lookup = await this.indexCache.getIndex(this.identityOf(url, provider.id), {
-      url,
-      label: name,
-      ...(options.provider === undefined ? {} : { provider: options.provider }),
-      force: true,
-    });
-
-    return {
-      name,
-      url,
-      provider: provider.id,
-      alreadyTrusted,
-      namespaces: Object.keys(lookup.index.namespaces).sort(),
-      recipeCount: Object.keys(lookup.index.recipes).length,
-      dryRun: false,
-    };
-  }
-
-  // --- Subscribing ------------------------------------------------------------------------------
-
-  /**
-   * Subscribes the project to a namespace or a recipe: resolves the whole
-   * dependency closure, trusts whatever new repositories that turns up, fetches
-   * every resolved version into the store, writes the lockfile and the managed
-   * subscriptions layer, and finally asks for the variables the new recipes
-   * publish.
-   *
-   * @param options - The ref, the prerelease and always-pull flags, and the trust flag.
-   */
-  async subscribe(options: SubscribeOptions): Promise<SubscribeOutcome> {
-    const dryRun = options.dryRun === true;
-
-    // What the ref names is settled here, from the cached indexes alone: a
-    // one-word ref is a guess at a name, and a location is matched against the
-    // repository at that location (trusted first, when it is not yet). Every
-    // step after this works with a fully qualified ref, so what is confirmed
-    // is exactly what is installed.
-    const { parsed, trusted: trustedForRef } = await this.resolveWrittenRef(options.ref, options);
-    const key = shortKey(parsed);
-
-    // The last gate before anything is fetched or written: what this will do to
-    // the project, in plain sentences, and a question.
-    await this.confirmSubscription(parsed, options);
-
-    const closure = await this.resolveClosure(parsed, options);
-    const { resolved, cycles } = closure;
-    const trusted = [...trustedForRef, ...closure.trusted];
-
-    const before = this.lock.read();
-    const after = this.lock.applyResolution(before, resolved, this.lockRepoInputs());
-    const diff = this.lock.diff(before, after);
-
-    const resolvedFrom =
-      options.ref.trim() === formatRef(parsed) ? {} : { resolvedFrom: options.ref.trim() };
-
-    if (dryRun) {
-      // The questions are planned even here, so `--dry-run` is the command an
-      // agent runs to find out what a subscription will want to know. Answers
-      // supplied with it are validated and reported, and nothing is written.
-      //
-      // What can be described is settled from the files actually on this
-      // machine, not from what the resolver happened to reach: a recipe already
-      // in the store, or read from a linked checkout, has its questions listed
-      // even when something else in the closure is still missing.
-      const defined = this.definedVariables(resolved);
-      const unreadable = this.unreadableRecipes(resolved);
-      const context = this.ladderContext();
-      const supplied = applyProvidedAnswers(defined, options.answers ?? [], context, {
-        sousDir: this.sousDir,
-        confDir: this.confDir,
-        interactive: this.interactive,
-        dryRun: true,
-      });
-
-      return {
-        ref: formatRef(parsed),
-        ...resolvedFrom,
-        key,
-        resolved,
-        trusted,
-        diff,
-        cycles,
-        questions: planQuestions(defined, context, { sousDir: this.sousDir }),
-        ...(unreadable.length === 0 ? {} : { unreadable }),
-        ...(supplied.stored.length === 0
-          ? {}
-          : { answers: { answered: supplied.stored, inherited: [], skipped: [] } }),
-        dryRun: true,
-      };
-    }
-
-    // Supplied answers are checked before anything is written, so an answer
-    // that does not fit, or a name nothing declares, fails the run rather than
-    // leaving a subscription behind with its questions unanswered.
-    validateProvidedAnswers(this.definedVariables(resolved), options.answers ?? []);
-
-    for (const recipe of resolved) await this.ensureStored(recipe);
-
-    this.lock.write(after);
-    this.writeSubscriptionEntry(key, parsed, options);
-
-    const answers = await this.askVariables(resolved, options.answers ?? []);
-
-    return {
-      ref: formatRef(parsed),
-      ...resolvedFrom,
-      key,
-      resolved,
-      trusted,
-      diff,
-      answers,
-      cycles,
-      dryRun: false,
-    };
-  }
-
-  // --- Working out what a one-word ref meant -----------------------------------------------------
-
-  /**
-   * Settles what a ref typed on the command line names, in any form it was
-   * written: a short ref goes through `resolveBareRef`; a location (a URL, an
-   * SSH remote, a provider-scheme locator, a browser URL) is matched against
-   * the trusted repository at that location and settled through its index.
-   * When no reading's repository is trusted yet, the trust ceremony runs for
-   * it first, exactly as it runs for a dependency's repository, and nothing is
-   * fetched from it before the answer.
-   *
-   * @param written - The ref exactly as the user wrote it.
-   * @param options - The trust and accept-first flags.
-   * @returns The fully qualified ref, and any repository trusted to settle it.
-   */
-  private async resolveWrittenRef(
-    written: string,
-    options: SubscribeOptions
-  ): Promise<{ parsed: NamedRef; trusted: string[] }> {
-    const { refs: readings } = sharedRefResolver().parse(written);
-    const short = readings.find(
-      (reading): reading is NamedRef => isNamedRef(reading) && locationOf(reading) === undefined
-    );
-    if (short !== undefined) {
-      return { parsed: await this.resolveBareRef(short, options), trusted: [] };
-    }
-
-    const trusted = await this.trustLocation(written, readings, options);
-    const chosen = await this.pickLocated(written, options.acceptFirst);
-    return { parsed: chosen, trusted };
-  }
-
-  /**
-   * The one namespace or recipe a location names among the trusted
-   * repositories, settled through their cached indexes and chosen between the
-   * way every reference is.
-   *
-   * @param written - The location as written.
-   * @param acceptFirst - Whether `--accept-first` was passed.
-   */
-  private async pickLocated(written: string, acceptFirst?: boolean): Promise<NamedRef> {
-    const repoOrder = this.repoSearchOrder();
-    const indexes = await this.loadIndexes(repoOrder);
-    this.indexesSnapshot = indexes;
-
-    const matches = await this.findNamed(written, repoOrder, indexes);
-
-    return this.pickNamed(matches, {
-      search: written.trim(),
-      ...(acceptFirst === undefined ? {} : { acceptFirst }),
-      details: [
-        `  The repository at that location is trusted, but its index publishes no namespace ` +
-          `or recipe there.`,
-        `  Run 'sous repo list --latest' to read what it publishes now.`,
-      ],
-    });
-  }
-
-  /**
-   * What a ref names among the trusted repositories' cached indexes, of the
-   * kinds given. Each repository carries the location it lives at, so a ref
-   * written as a location finds it whatever this project calls it.
-   *
-   * @param input - The ref exactly as it was written.
-   * @param repoOrder - The repositories, in search order.
-   * @param indexes - Their indexes.
-   * @param kinds - The kinds of ref this step accepts.
-   */
-  private async findRefs(
-    input: string,
-    repoOrder: string[],
-    indexes: Map<string, IndexFile>,
-    kinds: readonly RefKind[]
-  ): Promise<SousRef[]> {
-    const repos = this.resolverRepos();
-    const urls: Record<string, string | undefined> = {};
-    for (const name of repoOrder) urls[name] = repos[name]?.url;
-    const lookup = new CachedIndexLookup(indexes, { order: repoOrder, urls });
-    const result = await sharedRefResolver().resolve(
-      new RefResolveArguments({ input, lookup, kinds, refusedIsEmpty: true })
-    );
-    return result.refs;
-  }
-
-  /** What a ref names among the trusted repositories, as a namespace or a recipe. */
-  private async findNamed(
-    input: string,
-    repoOrder: string[],
-    indexes: Map<string, IndexFile>
-  ): Promise<NamedRef[]> {
-    return (await this.findRefs(input, repoOrder, indexes, ["namespace", "recipe"])) as NamedRef[];
-  }
-
-  /**
-   * Settles on one of several refs, the way every command does: one proceeds,
-   * several are chosen between through this service's own prompt, and
-   * `--accept-first` takes the first.
-   *
-   * @param matches - What the ref could have meant, in listing order.
-   * @param args - What the shared picker is told, less this service's own seams.
-   */
-  private async pickRef(
-    matches: SousRef[],
-    args: Omit<ConstructorParameters<typeof RefPickArguments>[0], "interactive" | "write" | "choose">
-  ): Promise<SousRef> {
-    return sharedRefPicker().pick(
-      matches,
-      new RefPickArguments({
-        ...args,
-        interactive: this.interactive,
-        write: (message: string) => this.write(message),
-        choose: (message, offered) => this.choose(message, offered),
-      })
-    );
-  }
-
-  /** `pickRef` for a step that only offers namespaces and recipes. */
-  private async pickNamed(
-    matches: NamedRef[],
-    args: Omit<ConstructorParameters<typeof RefPickArguments>[0], "interactive" | "write" | "choose">
-  ): Promise<NamedRef> {
-    return (await this.pickRef(matches, args)) as NamedRef;
-  }
-
-  /**
-   * Makes sure the repository a located ref names is trusted: nothing happens
-   * when any reading's repository already is. Otherwise the one repository the
-   * location names goes through the trust ceremony; a location that reads as
-   * several repositories (a GitLab URL with nested groups) is first a question
-   * of which one, since nothing may be fetched from a repository to find out
-   * before it is trusted.
-   *
-   * @param written - The location as written.
-   * @param readings - Every reading of it.
-   * @param options - The trust and accept-first flags.
-   * @returns The short names of the repositories trusted here.
-   */
-  private async trustLocation(
-    written: string,
-    readings: SousRef[],
-    options: SubscribeOptions
-  ): Promise<string[]> {
-    const repos = this.resolverRepos();
-    const known = new Set(Object.values(repos).map((repo) => repo.identity));
-    const located = readings.filter((reading) => locationOf(reading) !== undefined);
-    if (located.some((reading) => known.has(locationOf(reading)!.identity))) return [];
-
-    let chosen = located[0]!;
-    const identities = new Set(located.map((reading) => locationOf(reading)!.identity));
-    if (identities.size > 1) {
-      chosen = await this.pickRef(located, {
-        search: written.trim(),
-        ...(options.acceptFirst === undefined ? {} : { acceptFirst: options.acceptFirst }),
-        prompt: `'${written.trim()}' can be read as more than one repository. Which one?`,
-      });
-    }
-
-    const location = locationOf(chosen)!;
-    const outcome = await this.trust.confirmTrust(
-      [
-        {
-          name: proposeRepoName(repos, location.identity),
-          url: location.url,
-          identity: location.identity,
-          provider: location.provider,
-          requiredBy: [{ ref: written.trim(), requestedBy: PROJECT_REQUESTER }],
-        },
-      ],
-      {
-        interactive: this.interactive,
-        ...(options.trust === undefined ? {} : { trustFlag: options.trust }),
-      }
-    );
-    return outcome.added;
-  }
-
-  /**
-   * Settles what a ref names, reading nothing but the cached indexes.
-   *
-   * A ref with two segments already says what it names and is handed back
-   * untouched. A ref with one segment is resolved through the ref resolver
-   * (`src/services/ref-resolver/`), over namespaces and recipes only:
-   * nothing found is an error naming what was searched, one match is used and
-   * reported, and several are chosen between. `--accept-first` takes the first
-   * match in the documented order; a run that cannot ask fails and says so.
-   *
-   * @param written - The ref exactly as the user wrote it.
-   * @param options - The accept-first flag.
-   */
-  private async resolveBareRef(
-    written: NamedRef,
-    options: SubscribeOptions
-  ): Promise<NamedRef> {
-    // A ref that names a recipe, spelled as it is published, says what it
-    // names already. One word, or a spelling in another case, is searched.
-    const writtenRepo = repoOf(written)?.name;
-    const key = shortKey(written);
-    const search = writtenRepo === undefined ? key : `${writtenRepo}:${key}`;
-    if (written.kind === "recipe" && key === key.toLowerCase()) {
-      return written;
-    }
-
-    const qualifier =
-      writtenRepo === undefined
-        ? undefined
-        : (matchNames(writtenRepo, Object.keys(this.currentRepos()))[0] ?? writtenRepo);
-    const repoOrder = this.repoSearchOrder(qualifier);
-    const indexes = await this.loadIndexes(repoOrder);
-    if (writtenRepo === undefined) this.indexesSnapshot = indexes;
-
-    const lookup = new CachedIndexLookup(indexes, { order: repoOrder });
-    const matches = (
-      await sharedRefResolver().resolve(
-        new RefResolveArguments({ input: search, lookup, kinds: ["namespace", "recipe"] })
-      )
-    ).refs as NamedRef[];
-
-    if (matches.length === 0) {
-      throw new ConfigError(
-        [
-          `Nothing called '${key}' was found: no namespace has that name, ` +
-            `and no recipe does either.`,
-          ...describeIndexSearch({ name: key, repoOrder, indexes }),
-          `  Run 'sous repo search ${key}' to look for something like it, or ` +
-            `'sous repo add <url>' to add the repository that publishes it.`,
-        ].join("\n")
-      );
-    }
-
-    const chosen = await this.pickNamed(matches, {
-      search,
-      ...(options.acceptFirst === undefined ? {} : { acceptFirst: options.acceptFirst }),
-    });
-
-    // The range the ref was written with says which version to use, never
-    // which thing is meant, so it is carried over to whatever was chosen.
-    const range = rangeOf(written);
-    return chosen.kind === "recipe" && range !== undefined ? { ...chosen, range } : chosen;
-  }
-
-  /**
-   * The repositories a one-word ref is searched in, in the order their
-   * candidates are listed: the built-in repository first, then the ones the
-   * config names, in the order the config names them.
-   *
-   * @param only - A repository qualifier from the ref, which narrows the search to it.
-   */
-  private repoSearchOrder(only?: string): string[] {
-    const repos = this.currentRepos();
-    const names = Object.keys(repos);
-
-    if (only !== undefined) {
-      if (!Object.hasOwn(repos, only)) {
-        throw new ConfigError(
-          `This project does not trust a repository called '${only}'.\n` +
-            (names.length > 0
-              ? `  It trusts: ${names.join(", ")}.`
-              : `  It trusts none yet.`) +
-            `\n  Add it with 'sous repo add <url> --name ${only}'.`
-        );
-      }
-      return [only];
-    }
-
-    const builtIn = names.filter((name) => isBuiltInEntry(repos[name]));
-    return [...builtIn, ...names.filter((name) => !builtIn.includes(name))];
-  }
-
-  /**
-   * Every trusted repository's index, loaded once per command. Whatever a
-   * one-word ref already loaded is reused, so confirming a subscription costs
-   * no extra lookups.
-   */
-  private async indexSnapshot(): Promise<Map<string, IndexFile>> {
-    if (this.indexesSnapshot === undefined) {
-      this.indexesSnapshot = await this.loadIndexes(this.repoSearchOrder());
-    }
-    return this.indexesSnapshot;
-  }
-
-  // --- The subscribe confirmation ----------------------------------------------------------------
-
-  /**
-   * Says what subscribing will do to this project, and asks whether to go on.
-   *
-   * This runs before anything is fetched or written, so a "no" costs nothing:
-   * the only thing read to get here is the cached index of each trusted
-   * repository. `--yes` skips the question, and a dry run states the plan and
-   * never asks, because a dry run has nothing to decline.
-   *
-   * @param parsed - The fully qualified ref being subscribed to.
-   * @param options - The yes and dry-run flags.
-   */
-  private async confirmSubscription(
-    parsed: NamedRef,
-    options: SubscribeOptions
-  ): Promise<void> {
-    const indexes = await this.indexSnapshot();
-    const plan = await this.subscriptionPlan(parsed, options, indexes);
-    for (const line of plan) this.write(line === "" ? "" : indent(line));
-
-    if (options.dryRun === true || options.yes === true) return;
-
-    if (!this.interactive) {
-      throw nonInteractiveError({
-        prompt: `whether to go ahead with subscribing to '${formatRef(parsed)}'`,
-        remedy:
-          "pass '--yes' (spelled '-y', '--force' or '--trust' if you prefer) to accept " +
-          "the plan above without being asked.",
-      });
-    }
-
-    const proceed = await this.ask("Proceed?");
-    if (!proceed) {
-      throw new ConfigError(
-        `Nothing was written: the subscription to '${formatRef(parsed)}' was declined.\n` +
-          `  Nothing was downloaded, no lockfile entry was made, and this project's ` +
-          `config is exactly as it was.`
-      );
-    }
-  }
-
-  /**
-   * The plan itself: what will be compiled, what can run, what will be asked,
-   * and what will be fetched, in plain sentences.
-   *
-   * @param parsed - The fully qualified ref being subscribed to.
-   * @param options - The prerelease flag, for the dependency peek.
-   */
-  private async subscriptionPlan(
-    parsed: NamedRef,
-    options: SubscribeOptions,
-    indexes: Map<string, IndexFile>
-  ): Promise<string[]> {
-    const target = formatRef(parsed);
-    const width = wrapColumns() - 4;
-    const lines: string[] = [""];
-
-    /** One sentence of the plan, wrapped and in the warning color. */
-    const sentence = (text: string): string[] =>
-      wrapText(text, width).map((line) => palette.warning(line));
-
-    /** One bullet of the plan, wrapped so its continuation hangs under the text. */
-    const bullet = (text: string): string[] =>
-      wrapText(`${BULLET} ${text}`, width, { hangingIndent: 2 }).map((line) =>
-        palette.warning(line)
-      );
-
-    if (parsed.kind === "namespace") {
-      const published = this.namespaceRecipes(parsed, indexes);
-      lines.push(
-        ...sentence(
-          `Subscribing to '${target}' subscribes this project to the whole ` +
-            `namespace '${parsed.name}', which means ${palette.highlight(
-              "every recipe in it, including ones published later"
-            )}.`
-        )
-      );
-      if (published.length > 0) {
-        lines.push(
-          ...sentence(`It publishes ${published.length} today: ${published.join(", ")}.`)
-        );
-      }
-    } else {
-      lines.push(
-        ...sentence(
-          `Subscribing to '${target}' installs the recipe '${parsed.name}' from ` +
-            `the namespace '${namespaceOf(parsed)!.name}'.`
-        )
-      );
-    }
-
-    lines.push("");
-    lines.push(...sentence("Here is what that does:"));
-    lines.push("");
-    lines.push(
-      ...bullet(
-        `The files it ships are compiled into this project on the next build, ` +
-          `which writes them into this project's agent directories.`
-      )
-    );
-    lines.push(
-      ...bullet(
-        `Any scripts it ships ${palette.highlight(
-          "can be run on this machine"
-        )} when an agent uses them. Sous does not run them itself, and it cannot ` +
-          `vouch for what they do.`
-      )
-    );
-    lines.push(
-      ...bullet(
-        `The variables it publishes are asked about at the end of this command, ` +
-          `and the answers are written into this project's env files.`
-      )
-    );
-    lines.push(
-      ...bullet(
-        `Its dependencies are fetched and pinned in this project's lockfile, at ` +
-          `the exact versions resolved now.`
-      )
-    );
-
-    const untrusted = await this.knownUntrustedDependencyRepos(parsed, options, indexes);
-    if (untrusted.length > 0) {
-      lines.push(
-        ...bullet(
-          `Some of what it needs lives in repositories this project ${palette.highlight(
-            "does not trust yet"
-          )}: ${untrusted.join(", ")}. You are asked about each one by name before ` +
-            `anything is fetched from it.`
-        )
-      );
-    } else {
-      lines.push(
-        ...bullet(
-          `If a dependency turns out to live in a repository this project does ` +
-            `not trust, sous stops and asks about that repository by name before ` +
-            `fetching anything from it.`
-        )
-      );
-    }
-
-    lines.push("");
-    return lines;
-  }
-
-  /**
-   * The recipes a namespace publishes today, as `namespace/recipe` keys.
-   *
-   * @param parsed - The fully qualified namespace ref.
-   */
-  private namespaceRecipes(parsed: NamedRef, indexes: Map<string, IndexFile>): string[] {
-    const repo = repoOf(parsed)?.name;
-    const index = repo === undefined ? undefined : indexes.get(repo);
-    if (index === undefined) return [];
-    return Object.keys(index.recipes)
-      .filter((key) => key.startsWith(`${namespaceOf(parsed)!.name}/`))
-      .sort();
-  }
-
-  /**
-   * Repositories a dependency needs that this project does not trust, as far as
-   * anything already on disk knows.
-   *
-   * A manifest is the only thing that names a dependency, and a manifest that
-   * has never been fetched cannot be read without fetching, which is exactly
-   * what the confirmation exists to gate. So this reads what the store already
-   * holds, and says nothing when it holds nothing; the trust ceremony during
-   * resolution is still where the real answer comes from.
-   *
-   * @param parsed - The fully qualified ref being subscribed to.
-   * @param options - The prerelease flag.
-   */
-  private async knownUntrustedDependencyRepos(
-    parsed: NamedRef,
-    options: SubscribeOptions,
-    indexes: Map<string, IndexFile>
-  ): Promise<string[]> {
-    try {
-      const result = await resolveRefs(
-        [
-          {
-            ref: parsed,
-            requestedBy: PROJECT_REQUESTER,
-            kind: "subscribes",
-            ...(options.prerelease === true ? { prerelease: true } : {}),
-          },
-        ],
-        {
-          indexes,
-          repos: this.resolverRepos(),
-          // Reads only what is already on disk: the confirmation must not fetch.
-          loadManifest: (recipe) => this.loadRecipeManifest(recipe, true),
-          ...(options.prerelease === true ? { prerelease: true } : {}),
-        }
-      );
-      return result.missingRepos.map((missing) => `'${missing.name}'`).sort();
-    } catch {
-      // The plan is a courtesy; a peek that fails must never stop a subscription
-      // that resolution itself would have completed.
-      return [];
-    }
-  }
-
-  /**
-   * Resolves a ref and everything beneath it, running the trust round as often
-   * as resolution keeps turning up repositories the project has not added.
-   *
-   * IN PRACTICE THIS RUNS AT MOST ONE TRUST ROUND TODAY, and the loop is the
-   * shape rather than the behavior. A recipe names the repository it depends on
-   * by short name only, so nothing in a manifest carries a URL and every missing
-   * repository comes back under `needUrl`, which throws below. The loop earns
-   * its keep the moment any source of URLs exists (a repository hint block, or
-   * the lockfile of a project restoring someone else's commit); until then, read
-   * it as "one round, then either resolution succeeds or the person is told what
-   * to add".
-   *
-   * @param parsed - The ref being subscribed to.
-   * @param options - The prerelease and trust flags.
-   */
-  private async resolveClosure(
-    parsed: NamedRef,
-    options: SubscribeOptions
-  ): Promise<{
-    resolved: ResolvedRecipe[];
-    trusted: string[];
-    cycles: string[][];
-    unreadable: string[];
-  }> {
-    const trusted: string[] = [];
-
-    for (;;) {
-      const repos = this.resolverRepos();
-      const indexes = await this.loadIndexes(Object.keys(repos));
-
-      const result = await resolveRefs(
-        [
-          {
-            ref: parsed,
-            requestedBy: PROJECT_REQUESTER,
-            kind: "subscribes",
-            ...(options.prerelease === true ? { prerelease: true } : {}),
-          },
-        ],
-        {
-          indexes,
-          repos,
-          loadManifest: (recipe) => this.loadRecipeManifest(recipe, options.dryRun === true),
-          ...(options.prerelease === true ? { prerelease: true } : {}),
-        }
-      );
-
-      if (result.missingRepos.length === 0) {
-        // A dry run refuses to download, so a recipe this machine does not hold
-        // yet has no manifest to read. That is not a failure here: the plan
-        // describes everything it could read and names what it could not.
-        if (result.missingManifests.length > 0 && options.dryRun !== true) {
-          throw new ConfigError(
-            `Sous could not read the manifest of ` +
-              `${result.missingManifests.map((entry) => `'${entry}'`).join(", ")}.\n` +
-              `  Every recipe carries a manifest, so this one is either damaged upstream ` +
-              `or could not be downloaded. Nothing was written.`
-          );
-        }
-        return {
-          resolved: result.resolved,
-          trusted,
-          cycles: result.cycles,
-          unreadable: result.missingManifests,
-        };
-      }
-
-      const outcome = await this.trust.confirmTrust(result.missingRepos, {
-        interactive: this.interactive,
-        ...(options.trust === undefined ? {} : { trustFlag: options.trust }),
-      });
-
-      if (outcome.needUrl.length > 0) {
-        const lines = [
-          outcome.needUrl.length === 1
-            ? `Sous does not know where the repository '${outcome.needUrl[0]}' lives, so it ` +
-              `cannot add it for you.`
-            : `Sous does not know where these repositories live, so it cannot add them for ` +
-              `you: ${outcome.needUrl.map((entry) => `'${entry}'`).join(", ")}.`,
-          "  A recipe names the repository it depends on by its short name only; the URL " +
-            "has to come from you.",
-          "  Add each one with its URL, then run this command again:",
-          "",
-        ];
-        for (const name of outcome.needUrl) {
-          lines.push(`    sous repo add <url> --name ${name}`);
-        }
-        throw new ConfigError(lines.join("\n"));
-      }
-
-      trusted.push(...outcome.added);
-    }
-  }
-
-  /**
-   * The subscription key a ref typed on the command line names. A short ref
-   * names its own key, matched against the keys in force exactly first and then
-   * ignoring case; a location is settled through the trusted repository at that
-   * location, the way `subscribe` settles one.
-   *
-   * @param written - The ref as typed.
-   * @param keys - The subscription keys in force.
-   */
-  private async subscriptionKeyFor(written: string, keys: string[]): Promise<string> {
-    const { refs: readings } = sharedRefResolver().parse(written);
-    const short = readings.find(
-      (reading): reading is NamedRef => isNamedRef(reading) && locationOf(reading) === undefined
-    );
-    if (short !== undefined) {
-      const key = shortKey(short);
-      return matchNames(key, new Set(keys))[0] ?? key;
-    }
-    const chosen = await this.pickLocated(written);
-    return shortKey(chosen);
-  }
-
-  /**
-   * Removes one subscription and everything that was only there because of it.
-   * Removal is refcounted: a recipe another subscription (or another recipe)
-   * still holds stays exactly where it is, and is reported as having stayed.
-   *
-   * @param options - The ref to unsubscribe from.
-   */
-  async unsubscribe(options: UnsubscribeOptions): Promise<UnsubscribeOutcome> {
-    const dryRun = options.dryRun === true;
-
-    const managed = this.readSubscriptionEntries();
-    const configured = enabledSubscriptions(this.settings);
-    const key = await this.subscriptionKeyFor(options.ref, [
-      ...Object.keys(managed),
-      ...Object.keys(configured),
-    ]);
-    const before = this.lock.read();
-    const held = this.keysHeldBySubscription(before, key);
-
-    // An entry the managed layer already switched off is not a subscription any
-    // more, so removing it again is the "you do not subscribe to this" case
-    // rather than a deletion that would quietly switch it back on.
-    const alreadyOff = managed[key]?.enabled === false;
-    const removable = Object.hasOwn(managed, key) && !alreadyOff;
-    // Sous provides the `core` subscription itself, so there is no entry to
-    // delete. Removing it means recording an opt-out that outlives the default.
-    const builtIn = !removable && isBuiltInEntry(configured[key]);
-
-    if (!removable && !builtIn && !Object.hasOwn(configured, key) && held.length === 0) {
-      const known = [
-        ...new Set([
-          ...Object.entries(managed)
-            .filter(([, entry]) => entry?.enabled !== false)
-            .map(([entryKey]) => entryKey),
-          ...Object.keys(configured),
-        ]),
-      ].sort();
-      throw new ConfigError(
-        `This project does not subscribe to '${key}'.\n` +
-          (known.length > 0
-            ? `  It subscribes to: ${known.join(", ")}.`
-            : `  It has no subscriptions yet.`)
-      );
-    }
-
-    if (!removable && !builtIn && Object.hasOwn(configured, key)) {
-      throw new ConfigError(
-        `The subscription to '${key}' is written in this project's own config, not in the ` +
-          `layer sous manages.\n` +
-          `  Remove its entry from the 'subscriptions' block of your config file; sous ` +
-          `never edits a config file you wrote.`
-      );
-    }
-
-    let after = before;
-    for (const heldKey of held) after = this.dropProjectHold(after, heldKey);
-    const diff = this.lock.diff(before, after);
-
-    const stayed = held
-      .filter((heldKey) => Object.hasOwn(after.recipes, heldKey))
-      .map((heldKey) => ({
-        key: heldKey,
-        heldBy: [...after.recipes[heldKey]!.requestedBy],
-      }));
-
-    if (!dryRun) {
-      this.lock.write(after);
-
-      const remaining = { ...managed };
-      if (builtIn) remaining[key] = { enabled: false };
-      else delete remaining[key];
-
-      if (Object.keys(remaining).length === 0) {
-        removeManagedLayer(this.sousDir, SUBSCRIPTIONS_LAYER_FILENAME, {
-          confDir: this.confDir,
-        });
-      } else {
-        // A subscription sous provides itself has no entry to delete, so the
-        // opt-out is written as the entry instead; anything else is removed.
-        updateManagedLayer(
-          this.sousDir,
-          SUBSCRIPTIONS_LAYER_FILENAME,
-          [
-            {
-              path: ["subscriptions", key],
-              value: builtIn ? { enabled: false } : undefined,
-            },
-          ],
-          { confDir: this.confDir }
-        );
-      }
-    }
-
-    return { key, diff, stayed, optedOut: builtIn, dryRun };
-  }
-
-  // --- Withdrawing trust from a repository -------------------------------------------------------
-
-  /**
-   * Stops trusting a repository: every subscription that resolves into it is
-   * removed through the same refcounted path `unsubscribe` uses, the link that
-   * pointed at it is dropped, and its entry leaves the managed repositories
-   * layer.
-   *
-   * Informed consent, never prevention: everything that will go is printed
-   * first, in plain sentences, and then one question is asked. `--yes` skips the
-   * question and a dry run never asks, because a dry run has nothing to decline.
-   *
-   * The repository sous provides itself has no entry to delete, so removing it
-   * records `enabled: false` instead; the default comes back on every run and
-   * only a recorded opt-out outlives it.
-   *
-   * @param options - The repository's short name, and the yes and dry-run flags.
-   */
-  async removeRepo(options: RemoveRepoOptions): Promise<RemoveRepoOutcome> {
-    const name = options.name;
-    const dryRun = options.dryRun === true;
-
-    const trusted = this.trust.listTrusted();
-    const entry = trusted[name];
-    if (entry === undefined) {
-      const known = Object.keys(trusted).sort();
-      throw new ConfigError(
-        `This project does not trust a repository called '${name}'.\n` +
-          (known.length > 0
-            ? `  It trusts: ${known.join(", ")}.`
-            : `  It trusts no repositories yet.`)
-      );
-    }
-
-    const managed = this.trust.listManaged();
-    const builtIn = !Object.hasOwn(managed, name) && isBuiltInEntry(entry);
-    if (!Object.hasOwn(managed, name) && !builtIn) {
-      throw new ConfigError(
-        `The repository '${name}' is written in this project's own config, not in the ` +
-          `layer sous manages.\n` +
-          `  Remove its entry from the 'repos' block of your config file; sous never ` +
-          `edits a config file you wrote.`
-      );
-    }
-
-    const before = this.lock.read();
-    const { removable, kept } = this.subscriptionsInto(name, before);
-
-    // What the removal would leave behind, worked out before anything is
-    // written, so the plan below describes exactly what is about to happen.
-    let after = before;
-    const held: string[] = [];
-    for (const key of removable) {
-      for (const heldKey of keysHeldBySubscription(before, key)) {
-        held.push(heldKey);
-        after = this.dropProjectHold(after, heldKey);
-      }
-    }
-    const diff = this.lock.diff(before, after);
-    const removedRecipes = diff.removed.map((change) => change.key);
-    const stayed = [...new Set(held)]
-      .filter((heldKey) => Object.hasOwn(after.recipes, heldKey))
-      .sort()
-      .map((heldKey) => ({ key: heldKey, heldBy: [...after.recipes[heldKey]!.requestedBy] }));
-
-    const outputs = this.outputsOf(removedRecipes, options.scope);
-    const projectLink = readProjectLinks(this.sousDir).links[name];
-    const globalLink = readGlobalLinks(this.env).links[name];
-    const link = projectLink ?? globalLink;
-
-    const outcome: RemoveRepoOutcome = {
-      name,
-      url: entry.url,
-      optedOut: builtIn,
-      subscriptions: removable,
-      keptSubscriptions: kept,
-      removedRecipes,
-      stayed,
-      outputs,
-      diff,
-      ...(link === undefined ? {} : { linkedPath: link.path }),
-      linkIsGlobal: projectLink === undefined && globalLink !== undefined,
-      dryRun,
-    };
-
-    for (const line of this.removalPlan(outcome)) {
-      this.write(line === "" ? "" : indent(line));
-    }
-
-    if (!dryRun && options.yes !== true) {
-      if (!this.interactive) {
-        throw nonInteractiveError({
-          prompt: `whether to stop trusting the repository '${name}'`,
-          remedy:
-            "pass '--yes' (spelled '-y', '--force' or '-f' if you prefer) to accept the " +
-            "plan above without being asked.",
-        });
-      }
-
-      const proceed = await this.ask("Stop trusting it?");
-      if (!proceed) {
-        throw new ConfigError(
-          `Nothing was written: the repository '${name}' is still trusted.\n` +
-            `  No subscription was removed, no lockfile entry was changed, and this ` +
-            `project's config is exactly as it was.`
-        );
-      }
-    }
-
-    if (dryRun) return outcome;
-
-    // Each subscription goes through the ordinary refcounted removal, so a
-    // recipe another subscription still holds is kept exactly as it would be
-    // had the subscription been removed on its own.
-    for (const key of removable) await this.unsubscribe({ ref: key });
-
-    if (projectLink !== undefined) {
-      const map = readProjectLinks(this.sousDir);
-      delete map.links[name];
-      writeProjectLinks(this.sousDir, map);
-    }
-
-    if (builtIn) this.trust.disableRepo(name);
-    else this.trust.removeRepo(name);
-
-    return outcome;
-  }
-
-  /**
-   * The subscriptions that resolve into one repository, split by whether sous
-   * may remove them. A subscription counts when the lockfile pins one of its
-   * recipes to that repository, or when its ref names the repository outright
-   * with a `repo:` qualifier.
-   *
-   * @param name - The repository's short name.
-   * @param lock - The lockfile as it stands.
-   */
-  private subscriptionsInto(
-    name: string,
-    lock: Lockfile
-  ): { removable: string[]; kept: string[] } {
-    const fromRepo = new Set(
-      Object.entries(lock.recipes)
-        .filter(([, recipe]) => recipe.repo === name)
-        .map(([key]) => key)
-    );
-
-    const subscriptions = this.allSubscriptions();
-    const managed = this.readSubscriptionEntries();
-    const removable: string[] = [];
-    const kept: string[] = [];
-
-    for (const key of Object.keys(subscriptions).sort()) {
-      let qualifier: string | undefined;
-      try {
-        qualifier = repoOf(parseNamedRef(key, RefSource.Config))?.name;
-      } catch {
-        // A ref that does not parse cannot name this repository, and reporting
-        // it here would bury the removal under an unrelated complaint.
-        continue;
-      }
-
-      const touches =
-        qualifier === name ||
-        keysHeldBySubscription(lock, key).some((heldKey) => fromRepo.has(heldKey));
-      if (!touches) continue;
-
-      const sousMayRemove =
-        Object.hasOwn(managed, key) || isBuiltInEntry(subscriptions[key]);
-      if (sousMayRemove) removable.push(key);
-      else kept.push(key);
-    }
-
-    return { removable, kept };
-  }
-
-  /**
-   * The output files a set of locked recipes compiled, which the next build
-   * prunes once they are gone.
-   *
-   * Worked out from the recipes' own compile targets rather than from the build
-   * state file, because the state file records what sous wrote without
-   * recording which recipe wrote it. A destination that cannot be resolved
-   * (a `${var}` with no value in the scope given) leaves the list empty rather
-   * than stopping a removal; the build itself reports that properly.
-   *
-   * @param keys - The recipe keys that are going away.
-   * @param scope - The resolved settings scope, for `${var}` in destinations.
-   */
-  private outputsOf(keys: string[], scope?: VarScope): string[] {
-    if (keys.length === 0) return [];
-
-    const going = new Set(keys);
-    const locked = listLockedRecipes({ sousDir: this.sousDir, env: this.env }).filter(
-      (recipe) => going.has(recipe.key)
-    );
-    if (locked.length === 0) return [];
-
-    try {
-      const { targets } = buildRecipeTargets({
-        sousDir: this.sousDir,
-        settings: this.settings,
-        ...(scope === undefined ? {} : { scope }),
-        env: this.env,
-        locked,
-      });
-
-      const files = new Set<string>();
-      for (const target of targets) {
-        for (const output of target.outputs) {
-          const resolved = resolveOutputPath(target, output);
-          if (resolved !== undefined) files.add(resolved);
-        }
-      }
-      return [...files].sort();
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * What stopping trusting a repository will do to this project, in plain
-   * sentences: the entry itself, the subscriptions that go with it, the recipes
-   * they hold, the files the next build prunes, and the link that points at it.
-   *
-   * @param outcome - Everything the removal worked out.
-   */
-  private removalPlan(outcome: RemoveRepoOutcome): string[] {
-    const lines: string[] = [""];
-
-    lines.push(
-      outcome.optedOut
-        ? `The repository '${outcome.name}' at ${outcome.url} is one sous provides ` +
-            `itself, so it cannot be deleted: it is switched off instead, by recording ` +
-            `'${outcome.name}: { enabled: false }' in this project's repositories layer.`
-        : `The entry for '${outcome.name}' at ${outcome.url} is removed from this ` +
-            `project's repositories layer, so sous stops reading anything from it.`
-    );
-
-    lines.push("");
-    lines.push("Here is what goes with it:");
-    lines.push("");
-
-    if (outcome.subscriptions.length > 0) {
-      lines.push(
-        outcome.subscriptions.length === 1
-          ? `  One subscription resolves into it and is removed: ` +
-              `${outcome.subscriptions[0]}.`
-          : `  ${outcome.subscriptions.length} subscriptions resolve into it and are ` +
-              `removed: ${outcome.subscriptions.join(", ")}.`
-      );
-    } else {
-      lines.push("  Nothing this project subscribes to resolves into it.");
-    }
-
-    if (outcome.removedRecipes.length > 0) {
-      lines.push(
-        `  ${outcome.removedRecipes.length === 1 ? "One locked recipe is" : `${outcome.removedRecipes.length} locked recipes are`} ` +
-          `held only through those subscriptions, and ${
-            outcome.removedRecipes.length === 1 ? "it leaves" : "they leave"
-          } the lockfile: ${outcome.removedRecipes.join(", ")}.`
-      );
-    }
-
-    for (const stayed of outcome.stayed) {
-      lines.push(
-        `  The recipe '${stayed.key}' stays, because ${stayed.heldBy.join(", ")} still ` +
-          `holds it.`
-      );
-    }
-
-    if (outcome.outputs.length > 0) {
-      lines.push(
-        `  ${outcome.outputs.length === 1 ? "One file those recipes compiled is" : `${outcome.outputs.length} files those recipes compiled are`} ` +
-          `pruned by the build that follows:`
-      );
-      for (const file of outcome.outputs) lines.push(`    ${file}`);
-    }
-
-    if (outcome.linkedPath !== undefined) {
-      lines.push(
-        outcome.linkIsGlobal
-          ? `  A machine-wide link points this repository at the checkout at ` +
-              `${outcome.linkedPath}. That map is shared by every project on this ` +
-              `machine, so it is left exactly as it is, and the checkout stays on disk.`
-          : `  This project links the repository to the checkout at ` +
-              `${outcome.linkedPath}. The link is removed, and the checkout stays on ` +
-              `disk exactly as it is.`
-      );
-    }
-
-    for (const key of outcome.keptSubscriptions) {
-      lines.push(
-        `  The subscription to '${key}' resolves into it and is written in this ` +
-          `project's own config, which sous never edits, so it stays. It resolves ` +
-          `against nothing once the repository is gone.`
-      );
-    }
-
-    lines.push("");
-    return lines;
-  }
-
-  // --- Moving pins within their ranges -----------------------------------------------------------
-
-  /**
-   * Moves the lockfile's pins to the newest published versions their ranges
-   * allow, and nothing else: the subscriptions themselves are never edited, and
-   * no range is ever widened.
-   *
-   * The order is the design, as it is for subscribing:
-   *
-   *   - Every trusted repository's index is fetched fresh first. One that
-   *     cannot be reached is reported, and its pins stay exactly where they are.
-   *   - The reference, when there is one, is resolved through `src/services/ref-resolver/`
-   *     against those indexes, and it narrows which pins may move. Everything
-   *     outside it is held at its locked version for as long as its ranges
-   *     allow, so dependencies move with the closure and nothing else does.
-   *   - The whole change is printed as a plan and asked about once. With
-   *     nothing to change, nothing is asked. `--yes` accepts it; a run with no
-   *     terminal and no `--yes` fails naming the flag.
-   *   - Any repository a newer version needs that the project does not trust
-   *     goes through the usual trust question, and the plan is worked out again
-   *     once it is trusted.
-   *   - The lockfile is written, and then the questions the new versions ask
-   *     are asked, exactly as `subscribe` asks them.
-   *
-   * A subscription sous provides itself (the `core` namespace) never moves: its
-   * range is exactly the running sous version. Switched-off subscriptions take
-   * no part. A linked repository's pins move like any other, and builds keep
-   * reading its checkout until it is unlinked.
-   *
-   * @param options - What to update, and the confirmation, answer and dry-run flags.
-   */
-  async update(options: UpdateOptions = {}): Promise<UpdateOutcome> {
-    const dryRun = options.dryRun === true;
-
-    const repoNames = Object.keys(this.currentRepos()).sort();
-    const { indexes, unreachable } = await this.fetchFreshIndexes(repoNames);
-    const scope = await this.resolveUpdateScope(options, indexes);
-    const unreachableNames = new Set(unreachable.map((entry) => entry.repo));
-
-    let plan = await this.planUpdate(scope, indexes, unreachableNames, dryRun);
-    const facts = {
-      scope,
-      unreachable,
-      builtIn: this.builtInSubscriptionsIn(scope),
-      switchedOff: this.switchedOffSubscriptionsIn(scope),
-    };
-
-    const questions = planQuestions(this.definedVariables(plan.changed), this.ladderContext(), {
-      sousDir: this.sousDir,
-    }).filter((entry) => !entry.answered);
-
-    for (const line of formatUpdatePlan({
-      ...facts,
-      diff: plan.diff,
-      missingRepos: plan.missingRepos,
-      questions,
-      unreadable: dryRun ? this.unreadableRecipes(plan.changed) : [],
-      linked: plan.linked,
-      failed: plan.failed,
-    })) {
-      this.write(line === "" ? "" : indent(line));
-    }
-
-    const outcome = (trusted: string[], answers?: AskReport): UpdateOutcome => ({
-      scope,
-      diff: plan.diff,
-      nothingToUpdate: isEmptyUpdate(plan),
-      unreachable,
-      failed: plan.failed,
-      linked: plan.linked,
-      trusted,
-      ...(answers === undefined ? {} : { answers }),
-      cycles: plan.cycles,
-      dryRun,
-    });
-
-    if (isEmptyUpdate(plan) || dryRun) return outcome([]);
-
-    if (options.yes !== true) {
-      if (!this.interactive) {
-        throw nonInteractiveError({
-          prompt: `whether to update ${describeUpdateScope(scope)}`,
-          remedy:
-            "pass '--yes' (spelled '-y', '--force' or '--trust' if you prefer) to accept " +
-            "the plan above without being asked.",
-        });
-      }
-
-      const proceed = await this.ask("Update the lockfile?");
-      if (!proceed) {
-        throw new ConfigError(
-          `Nothing was written: the update was declined.\n` +
-            `  The lockfile and this project's config are exactly as they were.`
-        );
-      }
-    }
-
-    // A newer version that needs a repository this project does not trust is a
-    // trust decision, asked by name exactly as subscribing asks it. Once it is
-    // trusted, its index is read and the plan is worked out again, since the
-    // closure could not be walked past it before.
-    const trusted: string[] = [];
-    while (plan.missingRepos.length > 0) {
-      const decided = await this.trust.confirmTrust(plan.missingRepos, {
-        interactive: this.interactive,
-        ...(options.yes === undefined ? {} : { trustFlag: options.yes }),
-      });
-
-      if (decided.needUrl.length > 0) {
-        throw new ConfigError(
-          [
-            `Sous does not know where ${
-              decided.needUrl.length === 1
-                ? `the repository '${decided.needUrl[0]}' lives`
-                : `these repositories live: ${decided.needUrl.map((n) => `'${n}'`).join(", ")}`
-            }, so it cannot add ${decided.needUrl.length === 1 ? "it" : "them"} for you.`,
-            "  Nothing was written. Add each one with its URL, then run this command again:",
-            "",
-            ...decided.needUrl.map((name) => `    sous repo add <url> --name ${name}`),
-          ].join("\n")
-        );
-      }
-
-      trusted.push(...decided.added);
-      const added = await this.fetchFreshIndexes(decided.added);
-      for (const [name, index] of added.indexes) indexes.set(name, index);
-      plan = await this.planUpdate(scope, indexes, unreachableNames, false);
-    }
-
-    // Supplied answers are checked before anything is written, so one that does
-    // not fit fails the run rather than leaving the lockfile moved with its
-    // questions unanswered.
-    validateProvidedAnswers(this.definedVariables(plan.changed), options.answers ?? []);
-
-    for (const recipe of plan.changed) await this.ensureStored(recipe);
-    this.lock.write(plan.after);
-
-    const answers = await this.askVariables(plan.changed, options.answers ?? []);
-    return outcome(trusted, answers);
-  }
-
-  /**
-   * Fetches the index of each named repository straight from upstream,
-   * ignoring the freshness window. A repository that cannot be reached is
-   * reported rather than raised, and the copy already cached (when there is
-   * one) stands in for it so its pins can still be held where they are.
-   *
-   * @param names - The repositories' short names.
-   */
-  private async fetchFreshIndexes(names: string[]): Promise<{
-    indexes: Map<string, IndexFile>;
-    unreachable: Array<{ repo: string; reason: string }>;
-  }> {
-    const repos = this.currentRepos();
-    const indexes = new Map<string, IndexFile>();
-    const unreachable: Array<{ repo: string; reason: string }> = [];
-
-    for (const name of names) {
-      const entry = repos[name];
-      if (entry === undefined) continue;
-
-      let identity: string;
-      try {
-        identity = this.identityOf(entry.url, entry.provider);
-      } catch (error) {
-        unreachable.push({ repo: name, reason: describeError(error) });
-        continue;
-      }
-
-      try {
-        const lookup = await this.indexCache.refresh(identity, {
-          url: entry.url,
-          label: name,
-          ...(entry.provider === undefined ? {} : { provider: entry.provider }),
-        });
-        indexes.set(name, lookup.index);
-      } catch (error) {
-        unreachable.push({ repo: name, reason: describeError(error) });
-        const cached = this.indexCache.readCached(identity);
-        if (cached !== undefined) indexes.set(name, cached);
-      }
-    }
-
-    return { indexes, unreachable };
-  }
-
-  /**
-   * Settles what an update covers: a repository the caller named outright, the
-   * repository, namespace or recipe a reference names, or everything.
-   *
-   * @param options - The reference or repository, and the accept-first flag.
-   * @param indexes - The freshly fetched indexes, which the reference is resolved against.
-   */
-  private async resolveUpdateScope(
-    options: UpdateOptions,
-    indexes: Map<string, IndexFile>
-  ): Promise<UpdateScope> {
-    if (options.repo !== undefined) {
-      this.repoSearchOrder(options.repo);
-      return { kind: "repository", repo: options.repo };
-    }
-    if (options.ref === undefined) return { kind: "all" };
-
-    const repoOrder = this.repoSearchOrder();
-    const repos = this.currentRepos();
-    const urls: Record<string, string | undefined> = {};
-    for (const name of repoOrder) urls[name] = repos[name]?.url;
-
-    const matches = await this.findRefs(options.ref, repoOrder, indexes, [
-      "repo",
-      "namespace",
-      "recipe",
-    ]);
-
-    const chosen = await this.pickRef(matches, {
-      search: options.ref,
-      ...(options.acceptFirst === undefined ? {} : { acceptFirst: options.acceptFirst }),
-      details: [
-        `  No trusted repository, namespace or recipe has that name.`,
-        ...describeIndexSearch({ name: options.ref, repoOrder, indexes }),
-      ],
-    });
-
-    switch (chosen.kind) {
-      case "repo":
-        return { kind: "repository", repo: chosen.name! };
-      case "namespace":
-        return { kind: "namespace", repo: repoOf(chosen)!.name!, namespace: chosen.name };
-      default:
-        return {
-          kind: "recipe",
-          repo: repoOf(chosen)!.name!,
-          key: shortKey(chosen as NamedRef),
-        };
-    }
-  }
-
-  /**
-   * Works out what an update would do, writing nothing.
-   *
-   * Every subscription the scope touches is resolved afresh against the indexes
-   * given, one at a time so one that cannot be resolved does not stop the
-   * others, with every pin outside the scope held where the lockfile has it.
-   * What the resolutions settle on is laid over the lockfile, and every hold the
-   * new closure no longer declares is released, refcounted, so a dependency a
-   * newer version dropped leaves the lockfile unless something else still holds
-   * it.
-   *
-   * @param scope - What may move.
-   * @param indexes - The indexes to resolve against.
-   * @param unreachable - Repositories whose pins must not move, because their
-   *   index could not be fetched.
-   * @param dryRun - When true, read manifests only from disk and download nothing.
-   */
-  private async planUpdate(
-    scope: UpdateScope,
-    indexes: Map<string, IndexFile>,
-    unreachable: Set<string>,
-    dryRun: boolean
-  ): Promise<{
-    after: Lockfile;
-    diff: LockDiff;
-    changed: ResolvedRecipe[];
-    missingRepos: MissingRepo[];
-    failed: Array<{ key: string; reason: string }>;
-    linked: string[];
-    cycles: string[][];
-  }> {
-    const before = this.lock.read();
-    const subscriptions = this.allSubscriptions();
-    const repos = this.resolverRepos();
-
-    /** True when the update may move this recipe. */
-    const movable = (key: string, repo: string): boolean => {
-      if (unreachable.has(repo)) return false;
-      if (key === CORE_RECIPE_KEY && this.isBuiltInSubscription(CORE_NAMESPACE)) {
-        return false;
-      }
-      return recipeInScope(scope, key, repo);
-    };
-
-    // Everything the update may not move is held where the lockfile has it.
-    const keep: Record<string, string> = {};
-    for (const [key, entry] of Object.entries(before.recipes)) {
-      if (!movable(key, entry.repo)) keep[key] = entry.version;
-    }
-
-    const targets = Object.keys(subscriptions)
-      .sort()
-      .filter((key) => !this.isBuiltInSubscription(key))
-      .filter((key) => this.subscriptionTouches(key, scope, before, movable));
-
-    const merged = new Map<string, ResolvedRecipe>();
-    const resolvedSubscriptions: string[] = [];
-    const missing = new Map<string, MissingRepo>();
-    const failed: Array<{ key: string; reason: string }> = [];
-    const cycles: string[][] = [];
-
-    for (const key of targets) {
-      const entry = subscriptions[key]!;
-      let request: RefRequest;
-      try {
-        request = {
-          ref: parseNamedRef(key, RefSource.Config),
-          ...(entry.range === undefined ? {} : { range: entry.range }),
-          requestedBy: PROJECT_REQUESTER,
-          kind: "subscribes",
-          ...(entry.prerelease === true ? { prerelease: true } : {}),
-        };
-      } catch (error) {
-        failed.push({ key, reason: describeError(error) });
-        continue;
-      }
-
-      let result;
-      try {
-        result = await resolveRefs([request], {
-          indexes,
-          repos,
-          keep,
-          loadManifest: (recipe) => this.loadRecipeManifest(recipe, dryRun),
-          ...(entry.prerelease === true ? { prerelease: true } : {}),
-        });
-      } catch (error) {
-        failed.push({ key, reason: describeError(error) });
-        continue;
-      }
-
-      cycles.push(...result.cycles);
-      for (const repo of result.missingRepos) {
-        const known = missing.get(repo.name);
-        if (known === undefined) missing.set(repo.name, { ...repo });
-        else known.requiredBy.push(...repo.requiredBy);
-      }
-
-      let conflict = false;
-      for (const recipe of result.resolved) {
-        const already = merged.get(recipe.key);
-        if (already !== undefined && already.version !== recipe.version) {
-          failed.push({
-            key,
-            reason:
-              `It wants version ${recipe.version} of '${recipe.key}', and another ` +
-              `subscription wants ${already.version}.`,
-          });
-          conflict = true;
-          break;
-        }
-      }
-      if (conflict) continue;
-
-      for (const recipe of result.resolved) {
-        const already = merged.get(recipe.key);
-        merged.set(recipe.key, already === undefined ? recipe : mergeHolders(already, recipe));
-      }
-      resolvedSubscriptions.push(key);
-    }
-
-    const settled = [...merged.values()];
-    const applied = this.lock.applyResolution(before, settled, this.lockRepoInputs());
-    const others = Object.keys(subscriptions).filter(
-      (key) => !resolvedSubscriptions.includes(key)
-    );
-    const after = this.releaseDroppedHolds(applied, merged, resolvedSubscriptions, others);
-    const diff = this.lock.diff(before, after);
-
-    const changed = settled.filter(
-      (recipe) => before.recipes[recipe.key]?.version !== recipe.version
-    );
-    const linked = [
-      ...new Set(
-        changed
-          .map((recipe) => recipe.repo)
-          .filter((repo) => linkedPathFor(repo, this.sousDir, this.env) !== undefined)
-      ),
-    ].sort();
-
-    return {
-      after,
-      diff,
-      changed,
-      missingRepos: [...missing.values()].sort((left, right) =>
-        left.name < right.name ? -1 : 1
-      ),
-      failed,
-      linked,
-      cycles,
-    };
-  }
-
-  /**
-   * True when a subscription reaches anything the update may move, which is
-   * what decides whether it is resolved again. A subscription with nothing
-   * locked yet counts when its own ref falls inside the scope.
-   *
-   * @param key - The subscription's ref key.
-   * @param scope - What the update covers.
-   * @param lock - The lockfile as it stands.
-   * @param movable - Whether one locked recipe may move.
-   */
-  private subscriptionTouches(
-    key: string,
-    scope: UpdateScope,
-    lock: Lockfile,
-    movable: (key: string, repo: string) => boolean
-  ): boolean {
-    if (scope.kind === "all") return true;
-
-    let parsed: NamedRef;
-    try {
-      parsed = parseNamedRef(key, RefSource.Config);
-    } catch {
-      return false;
-    }
-    const parsedRepo = repoOf(parsed)?.name;
-
-    const closure = lockedClosure(lock, keysHeldBySubscription(lock, shortKey(parsed)));
-    if (closure.some((held) => movable(held, lock.recipes[held]!.repo))) return true;
-
-    // Nothing locked reaches the scope, but the subscription may still name it:
-    // a namespace subscription gains the recipes a namespace publishes later.
-    if (parsedRepo !== undefined && parsedRepo !== scope.repo) return false;
-    const covered = shortKey(parsed);
-    switch (scope.kind) {
-      case "repository":
-        return parsedRepo === scope.repo;
-      case "namespace":
-        return covered === scope.namespace || covered.startsWith(`${scope.namespace}/`);
-      case "recipe":
-        return covered === scope.key || scope.key.startsWith(`${covered}/`);
-    }
-  }
-
-  /**
-   * Releases every hold the new resolution no longer declares.
-   *
-   * Laying a resolution over the lockfile only ever adds holders, which is right
-   * for a subscription and wrong for an update: a newer version that no longer
-   * depends on something must stop holding it, and a namespace that stopped
-   * publishing a recipe must stop holding that one. A hold is released when the
-   * holder was resolved again and did not declare the recipe this time; an entry
-   * left with no holders goes, and so does whatever only it was holding.
-   *
-   * @param lock - The lockfile with the resolution laid over it.
-   * @param merged - What the resolutions settled on, by key.
-   * @param resolvedSubscriptions - The subscriptions that were resolved again.
-   * @param otherSubscriptions - Subscriptions that were not, whose holds stand.
-   */
-  private releaseDroppedHolds(
-    lock: Lockfile,
-    merged: Map<string, ResolvedRecipe>,
-    resolvedSubscriptions: string[],
-    otherSubscriptions: string[]
-  ): Lockfile {
-    const coverOf = (key: string): string | undefined => {
-      try {
-        return shortKey(parseNamedRef(key, RefSource.Config));
-      } catch {
-        return undefined;
-      }
-    };
-    const covers = (cover: string | undefined, key: string): boolean =>
-      cover !== undefined && (key === cover || key.startsWith(`${cover}/`));
-    const resolvedCovers = resolvedSubscriptions.map(coverOf);
-    const otherCovers = otherSubscriptions.map(coverOf);
-
-    const recipes: Record<string, LockedRecipe> = { ...lock.recipes };
-    const orphaned: string[] = [];
-
-    for (const [key, entry] of Object.entries(lock.recipes)) {
-      const settled = merged.get(key);
-      const kept = entry.requestedBy.filter((holder) => {
-        if (holder === PROJECT_HOLDER) {
-          if (!resolvedCovers.some((cover) => covers(cover, key))) return true;
-          if (otherCovers.some((cover) => covers(cover, key))) return true;
-          return settled?.requestedBy.includes(PROJECT_HOLDER) === true;
-        }
-        if (!merged.has(holder)) return true;
-        return settled?.requestedBy.includes(holder) === true;
-      });
-
-      if (kept.length === entry.requestedBy.length) continue;
-      if (kept.length === 0) {
-        delete recipes[key];
-        orphaned.push(key);
-      } else {
-        recipes[key] = { ...entry, requestedBy: kept };
-      }
-    }
-
-    let result: Lockfile = { ...lock, recipes };
-    for (const key of orphaned) result = this.lock.removeHolder(result, key);
-    return result;
-  }
-
-  /**
-   * True when a subscription is one sous provides itself, which an update never
-   * moves: its range is exactly the running sous version.
-   *
-   * @param key - The subscription's ref key.
-   */
-  private isBuiltInSubscription(key: string): boolean {
-    const configured = enabledSubscriptions(this.settings) as Record<string, SubscriptionEntry>;
-    return isBuiltInEntry(configured[key]);
-  }
-
-  /**
-   * The subscriptions sous provides itself that an update of this scope would
-   * otherwise have covered, with the version each stays at, for the plan.
-   *
-   * @param scope - What the update covers.
-   */
-  private builtInSubscriptionsIn(
-    scope: UpdateScope
-  ): Array<{ key: string; version?: string }> {
-    const lock = this.lock.read();
-    return Object.keys(this.allSubscriptions())
-      .filter((key) => this.isBuiltInSubscription(key))
-      .filter((key) =>
-        keysHeldBySubscription(lock, key).some((held) =>
-          recipeInScope(scope, held, lock.recipes[held]!.repo)
-        )
-      )
-      .map((key) => {
-        const version = this.allSubscriptions()[key]?.range;
-        return { key, ...(version === undefined ? {} : { version }) };
-      });
-  }
-
-  /**
-   * The switched-off subscriptions an update of this scope leaves alone.
-   *
-   * @param scope - What the update covers.
-   */
-  private switchedOffSubscriptionsIn(scope: UpdateScope): string[] {
-    const declared: Record<string, SubscriptionEntry> = {
-      ...((this.settings.subscriptions ?? {}) as Record<string, SubscriptionEntry>),
-      ...this.readSubscriptionEntries(),
-    };
-
-    return Object.keys(declared)
-      .filter((key) => declared[key]?.enabled === false)
-      .filter((key) => {
-        if (scope.kind === "all") return true;
-        let parsed: NamedRef;
-        try {
-          parsed = parseNamedRef(key, RefSource.Config);
-        } catch {
-          return false;
-        }
-        const covered = shortKey(parsed);
-        switch (scope.kind) {
-          case "repository":
-            return repoOf(parsed)?.name === scope.repo;
-          case "namespace":
-            return covered === scope.namespace || covered.startsWith(`${scope.namespace}/`);
-          case "recipe":
-            return covered === scope.key || scope.key.startsWith(`${covered}/`);
-        }
-      })
-      .sort();
-  }
-
-  /**
-   * Fetches one repository's index with a short timeout and says which of its
-   * pins have a newer published version their ranges allow. Nothing moves; this
-   * is the fact `sous repo unlink` reports. A fetch that fails or takes too long
-   * is an answer too: that sous could not check.
-   *
-   * @param name - The repository's short name.
-   * @param options - How long to wait for the index, in milliseconds.
-   */
-  async newerPublishedVersions(
-    name: string,
-    options: { timeoutMs?: number } = {}
-  ): Promise<NewerVersionsReport> {
-    const timeoutMs = options.timeoutMs ?? NEWER_VERSION_CHECK_TIMEOUT_MS;
-    const lock = this.lock.read();
-    const entry = this.currentRepos()[name];
-    const url = entry?.url ?? lock.repos[name]?.url;
-    const identity = this.identityForRepo(name, lock);
-    if (url === undefined || identity === undefined) {
-      return {
-        checked: false,
-        reason: `This project does not trust a repository called '${name}'.`,
-      };
-    }
-
-    // The same deadline and the same comparison a build's newer-version report
-    // uses, so the two can never disagree about what counts as newer.
-    let index: IndexFile;
-    try {
-      index = (
-        await withDeadline(
-          (signal) =>
-            this.indexCache.refresh(identity, {
-              url,
-              label: name,
-              ...(entry?.provider === undefined ? {} : { provider: entry.provider }),
-              signal,
-            }),
-          timeoutMs
-        )
-      ).index;
-    } catch (error) {
-      return { checked: false, reason: describeError(error) };
-    } finally {
-      recordUpstreamCheck(this.indexCache, identity, this.now());
-    }
-
-    return {
-      checked: true,
-      newer: this.newerInRange(index, name, lock, this.allSubscriptions()),
-    };
-  }
-
-  /**
-   * Every recipe the lockfile pins from one repository that has a newer
-   * published version inside the range its holders declared, sorted by key.
-   * Ranges come from `effectiveRangeForHolders`, so nothing is ever reported
-   * past a constraint a dependency declared. A build's newer-version report and
-   * `sous repo unlink` both read it.
-   *
-   * @param index - The repository's index.
-   * @param repoName - The repository's short name.
-   * @param lock - The lockfile as it stands.
-   * @param subscriptions - Every subscription, for ranges and prerelease opt-ins.
-   */
-  private newerInRange(
-    index: IndexFile,
-    repoName: string,
-    lock: Lockfile,
-    subscriptions: Record<string, SubscriptionEntry>
-  ): NewerVersion[] {
-    const newer: NewerVersion[] = [];
-    for (const key of Object.keys(lock.recipes).sort()) {
-      const entry = lock.recipes[key]!;
-      if (entry.repo !== repoName) continue;
-      const range = this.effectiveRangeFor(key, entry, subscriptions);
-      if (range === undefined) continue;
-      const subscription = subscriptions[key] ?? subscriptions[namespaceOfKey(key)];
-
-      const found = findNewerInRange({
-        index,
-        key,
-        lockedVersion: entry.version,
-        ...(range === "*" ? {} : { range }),
-        ...(subscription?.prerelease === undefined
-          ? {}
-          : { prerelease: subscription.prerelease }),
-      });
-      if (found !== undefined) newer.push(found);
-    }
-    return newer;
-  }
-
-  // --- Restoring and upstream checks -------------------------------------------------------------
-
-  /**
-   * True when the lockfile pins something the store does not hold, which is the
-   * state of a fresh clone. A linked repository is read from its checkout and is
-   * never restored.
-   */
-  needsRestore(): boolean {
-    return listLockedRecipes({ sousDir: this.sousDir, env: this.env }).some(
-      (recipe) => !recipe.linked && !recipe.present
-    );
-  }
-
-  /**
-   * Puts the core recipe that ships inside the sous package into the store,
-   * writes a stand-in index for the official repository when nothing real has
-   * ever been fetched, and tells the index cache about the packaged version so
-   * it resolves even against a real index that has not published it yet. This
-   * runs before anything else a build does, because it is what lets a project
-   * resolve the `core` namespace at all, with or without a network.
-   *
-   * Idempotent, offline, and never fatal: a failure comes back in the report as
-   * a sentence to warn about.
-   */
-  async seedCore(): Promise<SeedCoreRecipeReport> {
-    if (this.seedReport !== undefined) return this.seedReport;
-    this.seedReport = await seedCoreRecipe({
-      store: this.storeInstance,
-      sousVersion: SOUS_VERSION,
-      now: this.now,
-      // Teaching the index cache what the package holds is what lets the seeded
-      // version resolve on a machine whose cached index is the real one and does
-      // not publish that version yet.
-      indexCache: this.indexCache,
-      warn: this.warn,
-    });
-    return this.seedReport;
-  }
-
-  /**
-   * Brings the lockfile in line with the subscriptions the config declares.
-   *
-   * A subscription is normally written by `sous subscribe`, which locks it on
-   * the spot. Two cases leave one declared but unlocked, and both have to work
-   * without anyone typing a command: a subscription hand-written into the config
-   * (or arriving with a colleague's commit), and the built-in `core`
-   * subscription, whose range is the running sous version and therefore changes
-   * every time sous is upgraded.
-   *
-   * So a subscription is resolved here when the lockfile pins nothing for it, or
-   * pins something its range no longer allows. Everything else is left exactly
-   * as the lockfile has it; a build never re-decides a version it already has.
-   *
-   * Nothing here is fatal and nothing here prompts. A build must not stop
-   * because a repository is unreachable, and it must never block on a question,
-   * so a subscription that cannot be resolved comes back in the report as a
-   * sentence to warn about.
-   */
-  async ensureSubscriptionsLocked(): Promise<SubscriptionSyncReport> {
-    const report: SubscriptionSyncReport = {
-      resolved: [],
-      added: [],
-      moved: [],
-      failed: [],
-    };
-
-    const subscriptions = this.allSubscriptions();
-    const before = this.lock.read();
-
-    const pending: Array<{ key: string; request: RefRequest }> = [];
-    for (const key of Object.keys(subscriptions).sort()) {
-      const entry = subscriptions[key]!;
-      if (this.subscriptionIsLocked(key, entry, before)) continue;
-
-      let parsed: NamedRef;
-      try {
-        parsed = parseNamedRef(key, RefSource.Config);
-      } catch (error) {
-        report.failed.push({ key, reason: describeError(error) });
-        continue;
-      }
-
-      pending.push({
-        key,
-        request: {
-          ref: parsed,
-          ...(entry.range === undefined ? {} : { range: entry.range }),
-          requestedBy: PROJECT_REQUESTER,
-          kind: "subscribes",
-          ...(entry.prerelease === true ? { prerelease: true } : {}),
-        },
-      });
-    }
-
-    if (pending.length === 0) return report;
-
-    const repos = this.resolverRepos();
-    const indexes = await this.loadIndexes(Object.keys(repos), { lock: before });
-
-    // Each subscription is resolved on its own. Resolving them together would be
-    // one call, but the resolver raises on the first ref it cannot settle, and a
-    // project should not lose four subscriptions because one of them names a
-    // recipe that no longer exists. What the separate resolutions produce is
-    // merged back together below, so a recipe two subscriptions both depend on
-    // still records both of them as holders.
-    const stored = new Map<string, ResolvedRecipe>();
-    for (const { key, request } of pending) {
-      let result;
-      try {
-        result = await resolveRefs([request], {
-          indexes,
-          repos,
-          loadManifest: (recipe) => this.loadRecipeManifest(recipe, false),
-        });
-      } catch (error) {
-        report.failed.push({ key, reason: describeError(error) });
-        continue;
-      }
-
-      // A repository something needs but the project has not added is a trust
-      // decision, and a build is the wrong moment to ask for one. Say which
-      // command grants it, and leave this subscription alone.
-      if (result.missingRepos.length > 0) {
-        const names = result.missingRepos.map((missing) => missing.name);
-        report.failed.push({
-          key,
-          reason:
-            `Sous has not been told where ${
-              names.length === 1
-                ? `the repository '${names[0]}' lives`
-                : `these repositories live: ${names.map((n) => `'${n}'`).join(", ")}`
-            }, so it could not be resolved.\n` +
-            names.map((name) => `  sous repo add <url> --name ${name}`).join("\n"),
-        });
-        continue;
-      }
-
-      let failed = false;
-      const settled: ResolvedRecipe[] = [];
-      for (const recipe of result.resolved) {
-        try {
-          await this.ensureStored(recipe);
-          settled.push(recipe);
-        } catch (error) {
-          report.failed.push({ key, reason: describeError(error) });
-          failed = true;
-          break;
-        }
-      }
-
-      if (failed) continue;
-      report.resolved.push(key);
-
-      for (const recipe of settled) {
-        const already = stored.get(recipe.key);
-        if (already === undefined) {
-          stored.set(recipe.key, recipe);
-          continue;
-        }
-
-        if (already.version !== recipe.version) {
-          report.failed.push({
-            key: recipe.key,
-            reason:
-              `Two of this project's subscriptions want different versions of ` +
-              `'${recipe.key}': ${already.version} and ${recipe.version}. Sous kept ` +
-              `${already.version}.\n` +
-              `  Subscribe to '${recipe.key}' directly, with the range you want, so ` +
-              `there is one answer.`,
-          });
-          continue;
-        }
-
-        stored.set(recipe.key, mergeHolders(already, recipe));
-      }
-    }
-
-    if (stored.size === 0) return report;
-
-    const settledRecipes = [...stored.values()];
-    const after = this.lock.applyResolution(before, settledRecipes, this.lockRepoInputs());
-    for (const recipe of settledRecipes) {
-      const previous = before.recipes[recipe.key];
-      if (previous === undefined) {
-        report.added.push({ key: recipe.key, version: recipe.version });
-      } else if (previous.version !== recipe.version) {
-        report.moved.push({
-          key: recipe.key,
-          from: previous.version,
-          to: recipe.version,
-        });
-      }
-    }
-
-    this.lock.write(after);
-    return report;
-  }
-
-  /**
-   * True when the lockfile already pins everything one subscription asks for, at
-   * a version its range still allows.
-   *
-   * @param key - The subscription's ref key: a namespace, or `namespace/recipe`.
-   * @param entry - The subscription entry, which carries the range.
-   * @param lock - The lockfile as it stands.
-   */
-  private subscriptionIsLocked(
-    key: string,
-    entry: SubscriptionEntry,
-    lock: Lockfile
-  ): boolean {
-    const matches = key.includes("/")
-      ? lock.recipes[key] === undefined
-        ? []
-        : [lock.recipes[key]!]
-      : Object.entries(lock.recipes)
-          .filter(([lockedKey]) => lockedKey.startsWith(`${key}/`))
-          .map(([, locked]) => locked);
-
-    if (matches.length === 0) return false;
-
-    const range = entry.range;
-    const includePrerelease = entry.prerelease === true;
-
-    return matches.every((locked) => {
-      if (!locked.requestedBy.includes(PROJECT_HOLDER)) return false;
-      if (range === undefined || range === "*") return true;
-      return semver.satisfies(locked.version, range, { includePrerelease });
-    });
-  }
-
-  /**
-   * Makes the store hold exactly what the lockfile pins. Nothing here decides a
-   * version and nothing here asks a question; that is what makes a fresh clone
-   * reproducible.
-   */
-  async restore(): Promise<RestoreReport> {
-    await this.seedCore();
-    const lock = this.lock.read();
-    if (Object.keys(lock.recipes).length === 0) {
-      return { restored: [], alreadyPresent: [] };
-    }
-
-    const indexes = await this.loadIndexes(Object.keys(lock.repos), { lock });
-    return this.lock.restore(lock, {
-      store: this.storeInstance,
-      indexes,
-      providers: this.providers,
-      providerOptions: this.providerOptions,
-    });
-  }
-
-  /**
-   * Looks upstream for every repository the lockfile pins something from, on
-   * the freshness window. A repository that prefers a newer in-range version
-   * moves the lockfile to it; every other repository is only read, and a newer
-   * in-range version it publishes is reported in `newer` without moving any
-   * pin. A failed check never breaks a build: for a repository that prefers
-   * newer versions it is warned about, and for the others it is quiet, capped
-   * at a short deadline, and the cached index answers instead.
-   *
-   * @param options - Whether to check regardless of the freshness window, which
-   *   window to use, and how long to wait for a repository checked only for the
-   *   newer-version report.
-   */
-  async checkUpstream(
-    options: { force?: boolean; freshnessSeconds?: number; newerCheckTimeoutMs?: number } = {}
-  ): Promise<UpstreamCheckReport> {
-    const report: UpstreamCheckReport = {
-      checked: [],
-      updated: [],
-      failed: [],
-      newer: [],
-      unchecked: [],
-    };
-    const lock = this.lock.read();
-    if (Object.keys(lock.recipes).length === 0) return report;
-
-    const storeSettings = resolveStoreSettings(this.settings);
-    const freshnessSeconds = options.freshnessSeconds ?? storeSettings.freshnessSeconds;
-    const repos = this.currentRepos();
-    const subscriptions = this.allSubscriptions();
-
-    let changed = false;
-    const recipes: Record<string, LockedRecipe> = { ...lock.recipes };
-
-    for (const repoName of Object.keys(lock.repos).sort()) {
-      const identity = this.identityForRepo(repoName, lock);
-      if (identity === undefined) continue;
-
-      const prefersNewer = this.prefersNewer(repoName, repos[repoName], lock, subscriptions);
-      const meta = this.indexCache.readMeta(identity);
-      const due = shouldCheckUpstream({
-        ...(meta?.lastCheckedAt === undefined ? {} : { lastCheckedAt: meta.lastCheckedAt }),
-        freshnessSeconds,
-        alwaysPull: prefersNewer,
-        ...(options.force === undefined ? {} : { force: options.force }),
-        now: this.now(),
-      });
-
-      if (!prefersNewer) {
-        await this.reportNewerVersions({
-          repoName,
-          identity,
-          due,
-          lock,
-          subscriptions,
-          report,
-          timeoutMs: options.newerCheckTimeoutMs ?? NEWER_VERSION_CHECK_TIMEOUT_MS,
-        });
-        continue;
-      }
-
-      if (!due) continue;
-
-      report.checked.push(repoName);
-
-      let index: IndexFile;
-      try {
-        const url = repos[repoName]?.url ?? lock.repos[repoName]!.url;
-        const providerId = repos[repoName]?.provider;
-        index = (
-          await this.indexCache.getIndex(identity, {
-            url,
-            label: repoName,
-            ...(providerId === undefined ? {} : { provider: providerId }),
-            force: true,
-          })
-        ).index;
-      } catch (error) {
-        report.failed.push({ repo: repoName, reason: describeError(error) });
-        // Recorded even though it failed, so an unreachable host is not retried
-        // on every single build.
-        recordUpstreamCheck(this.indexCache, identity, this.now());
-        continue;
-      }
-
-      recordUpstreamCheck(this.indexCache, identity, this.now());
-
-      for (const [key, entry] of Object.entries(recipes)) {
-        if (entry.repo !== repoName) continue;
-        const subscription = subscriptions[key] ?? subscriptions[namespaceOfKey(key)];
-
-        // Always-pull re-resolves WITHIN what was declared; it never widens it.
-        // A recipe held only through another recipe's `depends` has no
-        // subscription to read a range from, and treating that as "any version"
-        // would move it straight past the constraint the dependency declared.
-        const range = this.effectiveRangeFor(key, entry, subscriptions);
-        if (range === undefined) continue;
-
-        const newer = findNewerInRange({
-          index,
-          key,
-          lockedVersion: entry.version,
-          ...(range === "*" ? {} : { range }),
-          ...(subscription?.prerelease === undefined
-            ? {}
-            : { prerelease: subscription.prerelease }),
-        });
-        if (newer === undefined) continue;
-
-        const published = index.recipes[key]!.versions[newer.to]!;
-        try {
-          await this.fetchIntoStore({
-            identity,
-            key,
-            version: newer.to,
-            hash: published.hash,
-            tag: published.tag,
-            recipePath: index.recipes[key]!.path,
-            url: repos[repoName]?.url ?? lock.repos[repoName]!.url,
-            providerId: repos[repoName]?.provider,
-          });
-        } catch (error) {
-          report.failed.push({ repo: repoName, reason: describeError(error) });
-          continue;
-        }
-
-        recipes[key] = { ...entry, version: newer.to, hash: published.hash };
-        report.updated.push(newer);
-        changed = true;
-      }
-    }
-
-    if (changed) this.lock.write({ ...lock, recipes });
-    return report;
-  }
-
-  /**
-   * The newer-version report for one repository that does not prefer newer
-   * versions: reads its index (from upstream when the freshness window has
-   * lapsed, within a short deadline, and from the cache otherwise) and records
-   * every locked recipe from it that has a newer version in range. Nothing
-   * moves, and nothing here is ever an error: a check that fails or runs out of
-   * time is noted in `unchecked` and the cached index answers instead.
-   *
-   * @param input - The repository, whether a check is due, and the report to fill.
-   */
-  private async reportNewerVersions(input: {
-    repoName: string;
-    identity: string;
-    due: boolean;
-    lock: Lockfile;
-    subscriptions: Record<string, SubscriptionEntry>;
-    report: UpstreamCheckReport;
-    timeoutMs: number;
-  }): Promise<void> {
-    const { repoName, identity, lock, report } = input;
-    let index: IndexFile | undefined;
-
-    if (input.due) {
-      report.checked.push(repoName);
-      const repo = this.currentRepos()[repoName];
-      const url = repo?.url ?? lock.repos[repoName]!.url;
-      try {
-        index = (
-          await withDeadline(
-            (signal) =>
-              this.indexCache.refresh(identity, {
-                url,
-                label: repoName,
-                ...(repo?.provider === undefined ? {} : { provider: repo.provider }),
-                signal,
-              }),
-            input.timeoutMs
-          )
-        ).index;
-      } catch (error) {
-        report.unchecked.push({ repo: repoName, reason: describeError(error) });
-      }
-      // Recorded whatever happened, so an unreachable host costs one short wait
-      // per freshness window rather than one per build.
-      recordUpstreamCheck(this.indexCache, identity, this.now());
-    }
-
-    index ??= this.indexCache.readCached(identity);
-    if (index === undefined) return;
-
-    for (const newer of this.newerInRange(index, repoName, lock, input.subscriptions)) {
-      report.newer.push({ ...newer, repo: repoName });
-    }
-  }
-
-  /**
-   * Reads one trusted repository's index from upstream, without writing it to
-   * the cache: what a browsing command asked to read the latest uses. A failure
-   * is raised, so the caller can fall back to the cached copy and say so.
-   *
-   * @param name - The repository's short name.
-   */
-  async upstreamIndex(name: string): Promise<IndexFile> {
-    const repo = this.currentRepos()[name];
-    if (repo === undefined) {
-      throw new ConfigError(`This project trusts no repository called '${name}'.`);
-    }
-    const identity = this.identityOf(repo.url, repo.provider);
-    return this.indexCache.fetchUpstream(identity, {
-      url: repo.url,
-      ...(repo.provider === undefined ? {} : { provider: repo.provider }),
-    });
-  }
-
-  /**
-   * Everything a build needs done before it compiles: seed the packaged core
-   * recipe, restore whatever else the store is missing, then look upstream for
-   * the repositories that want a newer version. All three are quiet when there
-   * is nothing to do.
-   *
-   * @param options - Whether to force the upstream check, and which freshness window to use.
-   */
-  async prepareForBuild(
-    options: { force?: boolean; freshnessSeconds?: number } = {}
-  ): Promise<{
-    seed: SeedCoreRecipeReport;
-    subscriptions: SubscriptionSyncReport;
-    restored: RestoreReport | undefined;
-    upstream: UpstreamCheckReport;
-  }> {
-    const seed = await this.seedCore();
-    const subscriptions = await this.ensureSubscriptionsLocked();
-    let restored: RestoreReport | undefined;
-    if (this.needsRestore()) restored = await this.restore();
-    const upstream = await this.checkUpstream(options);
-    return { seed, subscriptions, restored, upstream };
-  }
-
-  // --- Reading the project's state ---------------------------------------------------------------
-
-  /**
-   * Every repository this project trusts, merging the config it was loaded with
-   * and the managed layer as it stands on disk right now. The layer is re-read
-   * because a trust round in this same process may have just written to it.
-   */
-  currentRepos(): Record<string, TrustedRepo> {
-    return {
-      ...(enabledRepos(this.settings) as Record<string, TrustedRepo>),
-      ...this.trust.listManaged(),
-    };
-  }
-
-  /**
-   * Every subscription in force, from the config and from the managed layer.
-   *
-   * The managed layer is re-read rather than taken from the loaded config,
-   * because a command in this same process may have just written to it; an entry
-   * it switches off is dropped here, so removing a subscription sous provides
-   * itself really does stop it being locked and built.
-   */
-  allSubscriptions(): Record<string, SubscriptionEntry> {
-    const merged: Record<string, SubscriptionEntry> = {
-      ...(enabledSubscriptions(this.settings) as Record<string, SubscriptionEntry>),
-      ...this.readSubscriptionEntries(),
-    };
-
-    for (const [key, entry] of Object.entries(merged)) {
-      if (entry?.enabled === false) delete merged[key];
-    }
-    return merged;
-  }
-
-  /**
-   * Every subscription this project declares, switched-off ones included, with
-   * the versions the lockfile pins because of each. Switched-off entries are
-   * kept because an opt-out is part of what a project subscribes to, and hiding
-   * it would make `sous subscription list` disagree with the config.
-   *
-   * Reads only what is already on disk, so the listing is safe offline.
-   */
-  listSubscriptions(): SubscriptionListing[] {
-    const entries: Record<string, SubscriptionEntry> = {
-      ...((this.settings.subscriptions ?? {}) as Record<string, SubscriptionEntry>),
-      ...this.readSubscriptionEntries(),
-    };
-
-    const lock = this.lock.read();
-
-    return Object.keys(entries)
-      .sort()
-      .map((key) => {
-        const entry = entries[key]!;
-        return {
-          key,
-          range: entry.range,
-          enabled: entry.enabled !== false,
-          addedBy: entry.addedBy,
-          pinned: keysHeldBySubscription(lock, key).map((heldKey) => ({
-            key: heldKey,
-            version: lock.recipes[heldKey]!.version,
-          })),
-        };
-      });
-  }
-
-  /** The trusted repositories in the shape the resolver reads. */
-  private resolverRepos(): Record<string, ResolverRepo> {
-    const repos: Record<string, ResolverRepo> = {};
-    for (const [name, entry] of Object.entries(this.currentRepos())) {
-      repos[name] = {
-        url: entry.url,
-        identity: this.identityOf(entry.url, entry.provider),
-        ...(entry.provider === undefined ? {} : { provider: entry.provider }),
-        ...(entry.alwaysPull === undefined ? {} : { alwaysPull: entry.alwaysPull }),
-      };
-    }
-    return repos;
-  }
-
-  /** The repository records the lockfile writes, keyed by short name. */
-  private lockRepoInputs(): Record<string, LockRepoInput> {
-    const inputs: Record<string, LockRepoInput> = {};
-    for (const [name, entry] of Object.entries(this.currentRepos())) {
-      inputs[name] = {
-        url: entry.url,
-        identity: this.identityOf(entry.url, entry.provider),
-        ...(entry.provider === undefined ? {} : { provider: entry.provider }),
-      };
-    }
-    return inputs;
-  }
-
-  /**
-   * The cached (or freshly fetched) index of each named repository. A repository
-   * whose index cannot be obtained at all is warned about and left out, so one
-   * unreachable host never blocks work on the others.
-   *
-   * @param names - The repositories to load indexes for.
-   * @param options - A lockfile to fall back to for a repository's URL.
-   */
-  async loadIndexes(
-    names: string[],
-    options: { lock?: Lockfile; force?: boolean } = {}
-  ): Promise<Map<string, IndexFile>> {
-    const repos = this.currentRepos();
-    const indexes = new Map<string, IndexFile>();
-    const freshnessSeconds = resolveStoreSettings(this.settings).freshnessSeconds;
-
-    for (const name of names) {
-      const url = repos[name]?.url ?? options.lock?.repos[name]?.url;
-      if (url === undefined) continue;
-
-      try {
-        const identity =
-          this.identityForRepo(name, options.lock) ??
-          this.identityOf(url, repos[name]?.provider);
-        const lookup = await this.indexCache.getIndex(identity, {
-          url,
-          label: name,
-          ...(repos[name]?.provider === undefined
-            ? {}
-            : { provider: repos[name]!.provider! }),
-          maxAgeSeconds: freshnessSeconds,
-          ...(options.force === undefined ? {} : { force: options.force }),
-        });
-        indexes.set(name, lookup.index);
-      } catch (error) {
-        this.warn(
-          `Sous could not read the index of the repository '${name}', so nothing in it ` +
-            `can be resolved right now.\n${describeError(error)}`
-        );
-      }
-    }
-
-    return indexes;
-  }
-
-  // --- The store ---------------------------------------------------------------------------------
-
-  /**
-   * The directory a resolved recipe's files are read from: a linked working copy
-   * when the repository is linked, otherwise its store entry.
-   *
-   * @param recipe - The resolved recipe.
-   */
-  private recipeDirectory(recipe: ResolvedRecipe): string {
-    const checkout = linkedPathFor(recipe.repo, this.sousDir, this.env);
-    if (checkout !== undefined) {
-      const linked = mapLinkedRecipes(checkout)[recipe.key];
-      if (linked !== undefined) return linked;
-    }
-    return this.storeInstance.entryDir(storeKeyFor(recipe));
-  }
-
-  /**
-   * Makes sure a resolved recipe's files are in the store, fetching them when
-   * they are not. A linked repository is read from its checkout and is never
-   * fetched.
-   *
-   * @param recipe - The resolved recipe.
-   */
-  private async ensureStored(recipe: ResolvedRecipe): Promise<void> {
-    if (linkedPathFor(recipe.repo, this.sousDir, this.env) !== undefined) return;
-
-    const key = storeKeyFor(recipe);
-    const hit = await this.storeInstance.get(key);
-    if (hit !== undefined && hit.entry.hash === recipe.hash) return;
-
-    // The store refuses to overwrite an entry whose content differs, because a
-    // published version is immutable and one that changed underneath a project
-    // is worth refusing loudly. There is exactly one entry that is not a
-    // published version: the packaged core recipe sous seeds so a project can
-    // build before it has ever reached the network. That copy is a stand-in for
-    // the published one, not a rival to it, so when the two disagree at the same
-    // version it steps aside and the published copy is fetched over it.
-    if (hit !== undefined && (await this.isSeededCoreEntry(key, hit.entry.hash))) {
-      await this.storeInstance.remove(key);
-    }
-
-    const repos = this.currentRepos();
-    const url = repos[recipe.repo]?.url;
-    if (url === undefined) {
-      throw new ConfigError(
-        `Sous cannot fetch '${recipe.key}' because it no longer knows where the ` +
-          `repository '${recipe.repo}' lives.\n` +
-          `  Add it with 'sous repo add <url> --name ${recipe.repo}'.`
-      );
-    }
-
-    await this.fetchIntoStore({
-      identity: recipe.identity,
-      key: recipe.key,
-      version: recipe.version,
-      hash: recipe.hash,
-      tag: recipe.tag,
-      recipePath: recipe.path,
-      url,
-      providerId: repos[recipe.repo]?.provider,
-    });
-  }
-
-  /**
-   * True when a store entry is the packaged core recipe that seeding put there,
-   * rather than anything fetched from a repository.
-   *
-   * The test is deliberately exact: the entry has to be the core recipe in the
-   * official repository, AND its content has to hash to what this installation's
-   * package holds. An entry that was genuinely fetched, or a seeded entry from a
-   * different installation, is left alone.
-   *
-   * @param key - The store key being written to.
-   * @param storedHash - The hash the entry currently holds.
-   */
-  private async isSeededCoreEntry(key: StoreKey, storedHash: string): Promise<boolean> {
-    if (key.identity !== OFFICIAL_REPO_IDENTITY) return false;
-    if (`${key.namespace}/${key.name}` !== CORE_RECIPE_KEY) return false;
-
-    try {
-      return (await hashDirectory(packagedCoreRecipeDir())) === storedHash;
-    } catch {
-      // No packaged recipe to compare against means nothing here was seeded.
-      return false;
-    }
-  }
-
-  /**
-   * Fetches one recipe version into the store, verifying it against the hash the
-   * index publishes. The download lands in a temporary directory beside the
-   * store, so a failed fetch never leaves a half-written entry behind.
-   *
-   * @param request - Which version to fetch, from where, and at which tag.
-   */
-  private async fetchIntoStore(request: {
-    identity: string;
-    key: string;
-    version: string;
-    hash: string;
-    tag: string;
-    recipePath: string;
-    url: string;
-    providerId?: string;
-  }): Promise<void> {
-    const provider = requireProvider(request.url, request.providerId, this.providers);
-    const canonical = provider.canonicalize(request.url);
-
-    const { namespace, name } = splitRecipeKey(request.key);
-    const key: StoreKey = {
-      identity: request.identity,
-      namespace,
-      name,
-      version: request.version,
-    };
-
-    ensureStoreRootDirectory(this.storeInstance.root);
-    const workDir = await fsp.mkdtemp(path.join(this.storeInstance.root, ".sous-fetch-"));
-    const fetchDir = path.join(workDir, key.name);
-    try {
-      await provider.fetchRecipeTree(
-        canonical,
-        request.recipePath,
-        request.tag,
-        fetchDir,
-        this.providerOptions
-      );
-      await this.storeInstance.put(key, fetchDir, request.hash);
-    } finally {
-      await fsp.rm(workDir, { recursive: true, force: true });
-    }
-  }
-
-  /**
-   * The manifest loader the resolver walks the dependency closure with. It
-   * fetches the recipe when the store does not hold it, which is the seam where
-   * "resolve" turns into "download"; a dry run refuses to fetch and reads only
-   * what is already there.
-   *
-   * @param recipe - The resolved recipe whose manifest is wanted.
-   * @param dryRun - When true, read what is on disk and download nothing.
-   */
-  private async loadRecipeManifest(
-    recipe: ResolvedRecipe,
-    dryRun: boolean
-  ): Promise<RecipeManifest | undefined> {
-    const directory = this.recipeDirectory(recipe);
-    const existing = readRecipeManifestIn(directory);
-    if (existing !== undefined) return existing;
-    if (dryRun) return undefined;
-
-    await this.ensureStored(recipe);
-    return readRecipeManifestIn(this.recipeDirectory(recipe));
-  }
-
-  // --- The managed subscriptions layer -----------------------------------------------------------
-
-  /** Every subscription written in the managed layer, keyed by ref key. */
-  private readSubscriptionEntries(): Record<string, SubscriptionEntry> {
-    const layer = readManagedLayer(this.sousDir, SUBSCRIPTIONS_LAYER_FILENAME, {
-      confDir: this.confDir,
-    });
-    const entries = layer["subscriptions"];
-    if (typeof entries !== "object" || entries === null || Array.isArray(entries)) return {};
-    return entries as Record<string, SubscriptionEntry>;
-  }
-
-  /**
-   * Records one subscription in the managed layer, editing only that entry.
-   *
-   * @param key - The ref key the subscription is recorded under.
-   * @param parsed - The ref as parsed, for its version range.
-   * @param options - The prerelease and always-pull flags.
-   */
-  private writeSubscriptionEntry(
-    key: string,
-    parsed: NamedRef,
-    options: SubscribeOptions
-  ): void {
-    const range = rangeOf(parsed);
-    const entry: SubscriptionEntry = {
-      ...(range === undefined ? {} : { range }),
-      ...(options.prerelease === true ? { prerelease: true } : {}),
-      ...(options.alwaysPull === true ? { alwaysPull: true } : {}),
-      addedAt: this.now().toISOString(),
-      addedBy: USER_ADDED_BY,
-    };
-
-    updateManagedLayer(
-      this.sousDir,
-      SUBSCRIPTIONS_LAYER_FILENAME,
-      [{ path: ["subscriptions", key], value: entry }],
-      { confDir: this.confDir }
-    );
-  }
-
-  // --- Lockfile bookkeeping ----------------------------------------------------------------------
-
-  /**
-   * The lockfile keys one subscription holds directly. The rule itself lives in
-   * `keysHeldBySubscription` (`locked-recipes.ts`), beside the other readers of
-   * the lockfile's holder lists.
-   *
-   * @param lock - The lockfile as it stands.
-   * @param key - The subscription's ref key.
-   */
-  private keysHeldBySubscription(lock: Lockfile, key: string): string[] {
-    return keysHeldBySubscription(lock, key);
-  }
-
-  /**
-   * Drops the project's own hold on one recipe. When something else still holds
-   * it the entry stays; when nothing does, the entry goes and everything it
-   * pulled in is reconsidered, which is what makes removal refcounted.
-   *
-   * @param lock - The lockfile as it stands.
-   * @param key - The recipe key to release.
-   */
-  private dropProjectHold(lock: Lockfile, key: string): Lockfile {
-    const entry = lock.recipes[key];
-    if (entry === undefined) return lock;
-
-    const kept = entry.requestedBy.filter((holder) => holder !== PROJECT_HOLDER);
-    const recipes = { ...lock.recipes };
-
-    if (kept.length > 0) {
-      recipes[key] = { ...entry, requestedBy: kept };
-      return { ...lock, recipes };
-    }
-
-    delete recipes[key];
-    return this.lock.removeHolder({ ...lock, recipes }, key);
-  }
-
-  /**
-   * True when a repository prefers a newer in-range version over the locked one,
-   * whether the flag is on the repository itself or on any subscription that
-   * resolves inside it.
-   *
-   * @param repoName - The repository's short name.
-   * @param repo - Its config entry, when it still has one.
-   * @param lock - The lockfile, for which recipes came from it.
-   * @param subscriptions - Every subscription, from the config and the managed layer.
-   */
-  private prefersNewer(
-    repoName: string,
-    repo: TrustedRepo | undefined,
-    lock: Lockfile,
-    subscriptions: Record<string, SubscriptionEntry>
-  ): boolean {
-    if (repo?.alwaysPull === true) return true;
-
-    for (const [key, entry] of Object.entries(subscriptions)) {
-      if (entry.alwaysPull !== true) continue;
-      const keys = this.keysHeldBySubscription(lock, key);
-      if (keys.some((held) => lock.recipes[held]!.repo === repoName)) return true;
-    }
-
-    return false;
-  }
-
-  /**
-   * The version range an always-pull check may move one locked recipe within,
-   * or undefined when sous cannot tell and therefore must not move it.
-   *
-   * The rule itself lives in `effectiveRangeForHolders`; this supplies it with
-   * the two lookups it needs, one reading the project's subscriptions and one
-   * reading the manifest of each holding recipe.
-   *
-   * @param key - The locked recipe key, `namespace/recipe`.
-   * @param entry - Its lockfile entry, for its holders.
-   * @param subscriptions - Every subscription, from the config and the managed layer.
-   */
-  private effectiveRangeFor(
-    key: string,
-    entry: LockedRecipe,
-    subscriptions: Record<string, SubscriptionEntry>
-  ): string | undefined {
-    const namespace = namespaceOfKey(key);
-    return effectiveRangeForHolders(key, entry.requestedBy, {
-      subscriptionRange: (held) => {
-        // A subscription the config no longer declares is not a hold sous can
-        // read a range from; leave the entry alone rather than guessing.
-        const subscription = subscriptions[held] ?? subscriptions[namespace];
-        return subscription === undefined ? undefined : (subscription.range ?? "*");
-      },
-      dependencyRange: (holder, held) =>
-        this.declaredDependencyRange(holder, held, namespace),
-    });
-  }
-
-  /**
-   * The range one recipe's manifest declares for a dependency, or undefined when
-   * its manifest cannot be read or no longer names that dependency.
-   *
-   * @param holder - The holding recipe's key, `namespace/recipe`.
-   * @param key - The held recipe's key.
-   * @param namespace - The held recipe's namespace, since a `depends` entry may
-   *   name a whole namespace rather than one recipe.
-   */
-  private declaredDependencyRange(
-    holder: string,
-    key: string,
-    namespace: string
-  ): string | undefined {
-    const directory = this.lockedRecipeDirectories()[holder];
-    if (directory === undefined) return undefined;
-
-    let manifest;
-    try {
-      manifest = readRecipeManifestIn(directory);
-    } catch {
-      return undefined;
-    }
-    if (manifest === undefined) return undefined;
-
-    for (const dependency of manifest.depends ?? []) {
-      // Every reading counts: a dependency that reads more than one way still
-      // declares its range for whichever reading the lockfile settled on.
-      let readings: SousRef[];
-      try {
-        readings = sharedRefResolver().parse(dependency, RefSource.Manifest).refs;
-      } catch {
-        continue;
-      }
-      for (const reading of readings) {
-        if (!isNamedRef(reading)) continue;
-        const dependencyKey = shortKey(reading);
-        if (dependencyKey !== key && dependencyKey !== namespace) continue;
-        return rangeOf(reading) ?? "*";
-      }
-    }
-
-    return undefined;
-  }
-
-  /**
-   * Where each locked recipe's files are, keyed by recipe key. Read once per
-   * command, because an always-pull check asks for the same answer for every
-   * entry in the lockfile.
-   */
-  private lockedRecipeDirectories(): Record<string, string> {
-    if (this.lockedDirectories === undefined) {
-      this.lockedDirectories = {};
-      for (const located of listLockedRecipes({ sousDir: this.sousDir, env: this.env })) {
-        if (located.present) this.lockedDirectories[located.key] = located.dir;
-      }
-    }
-    return this.lockedDirectories;
-  }
-
-  // --- Variables ----------------------------------------------------------------------------------
-
-  /**
-   * Every variable definition the resolved closure publishes, attributed to the
-   * recipe that declared it and to the chain that pulled it in.
-   *
-   * A recipe whose files are not on this machine is described from the
-   * definitions its index entry records, and contributes nothing rather than
-   * failing when the entry records none, which is what lets a dry run describe
-   * as much of the closure as it can without downloading any of it.
-   *
-   * @param resolved - The recipe versions the resolution settled on.
-   */
-  private definedVariables(resolved: ResolvedRecipe[]): DefinedVariable[] {
-    const defined: DefinedVariable[] = [];
-    const byKey = new Map(resolved.map((recipe) => [recipe.key, recipe]));
-    const repos = this.currentRepos();
-
-    /** One resolved recipe, described the way the variables layer shows it. */
-    const describe = (recipe: ResolvedRecipe): DefiningRecipe => {
-      const url = repos[recipe.repo]?.url;
-      return {
-        repo: recipe.repo,
-        namespace: recipe.namespace,
-        name: recipe.name,
-        version: recipe.version,
-        path: recipe.path,
-        dir: this.recipeDirectory(recipe),
-        ...(url === undefined ? {} : { url }),
-      };
-    };
-
-    /** How a recipe came to be here: the subscribed recipe first, then each holder. */
-    const chainFor = (recipe: ResolvedRecipe): ResolvedRecipe[] => {
-      const chain = [recipe];
-      const seen = new Set([recipe.key]);
-      let current = recipe;
-
-      while (!current.requestedBy.includes(PROJECT_HOLDER)) {
-        const holderKey = current.requestedBy.find(
-          (holder) => holder !== PROJECT_HOLDER && byKey.has(holder) && !seen.has(holder)
-        );
-        if (holderKey === undefined) break;
-        current = byKey.get(holderKey)!;
-        seen.add(holderKey);
-        chain.unshift(current);
-      }
-
-      return chain;
-    };
-
-    // The subscribed recipe's own questions come first, then each dependency in
-    // the order the closure reached it, so the run reads the way it happened.
-    const ordered = [...resolved].sort((left, right) => {
-      const depth = chainFor(left).length - chainFor(right).length;
-      return depth !== 0 ? depth : left.key.localeCompare(right.key);
-    });
-
-    for (const recipe of ordered) {
-      const variables = this.publishedVariables(recipe);
-      if (variables === undefined) continue;
-
-      const publisher = describe(recipe);
-      const requiredBy = chainFor(recipe).map(describe);
-      for (const definition of variables) {
-        defined.push({ definition, recipe: publisher, requiredBy });
-      }
-    }
-
-    return defined;
-  }
-
-  /**
-   * The recipes in a resolution whose manifests cannot be read from this
-   * machine, because neither the store nor a linked checkout holds their files
-   * yet. A dry run downloads nothing, so this is exactly the set whose
-   * questions it cannot describe; everything else is described in full.
-   *
-   * @param resolved - The recipe versions the resolution settled on.
-   */
-  private unreadableRecipes(resolved: ResolvedRecipe[]): string[] {
-    return resolved
-      .filter((recipe) => this.publishedVariables(recipe) === undefined)
-      .map((recipe) => recipe.key)
-      .sort();
-  }
-
-  /**
-   * The variable definitions one resolved recipe publishes: from its manifest
-   * when its files are on this machine (a linked checkout's working copy
-   * included), otherwise from its index entry, or undefined when neither can
-   * say.
-   *
-   * @param recipe - The resolved recipe.
-   */
-  private publishedVariables(recipe: ResolvedRecipe): VariableDefinition[] | undefined {
-    const manifest = readRecipeManifestIn(this.recipeDirectory(recipe));
-    if (manifest !== undefined) return manifest.variables ?? [];
-    return recipe.variables;
-  }
-
-  /**
-   * Works out what subscribing to a ref would install and which questions it
-   * would ask, from the indexes and the files already on this machine. Nothing
-   * is fetched, trusted or written, which is what lets `sous recipe show`
-   * describe a recipe before anyone subscribes to it. A repository the closure
-   * needs and the project does not trust is reported, and its recipes are not
-   * resolved.
-   *
-   * @param parsed - The fully qualified ref, with the exact version to describe as its range.
-   * @param options - The indexes to read, and whether prereleases may match.
-   */
-  async previewSubscription(
-    parsed: NamedRef,
-    options: PreviewSubscriptionOptions = {}
-  ): Promise<SubscriptionPreview> {
-    const repos = this.resolverRepos();
-    const indexes = options.indexes ?? (await this.loadIndexes(Object.keys(repos)));
-    const result = await resolveRefs(
-      [
-        {
-          ref: parsed,
-          requestedBy: PROJECT_REQUESTER,
-          kind: "subscribes",
-          ...(options.prerelease === true ? { prerelease: true } : {}),
-        },
-      ],
-      {
-        indexes,
-        repos,
-        loadManifest: (recipe) => this.loadRecipeManifest(recipe, true),
-        ...(options.prerelease === true ? { prerelease: true } : {}),
-      }
-    );
-
-    return {
-      resolved: result.resolved,
-      missingRepos: result.missingRepos,
-      questions: planQuestions(this.definedVariables(result.resolved), this.ladderContext(), {
-        sousDir: this.sousDir,
-      }),
-      unreadable: this.unreadableRecipes(result.resolved),
-      cycles: result.cycles,
-    };
-  }
-
-  /** The environment layers and mapping records this project resolves against. */
-  private ladderContext(): LadderContext {
-    return loadLadderContext({
-      sousDir: this.sousDir,
-      settings: this.settings,
-      shellEnv: this.shellEnv,
-    });
-  }
-
-  /**
-   * Asks for the variables the newly resolved recipes publish, keeping and
-   * reporting whatever answers were already in scope. Answers supplied ahead of
-   * the questions are validated and stored first, so only what is left over is
-   * asked for. A run with no terminal fails naming the exact environment
-   * variables that would answer each remaining question, which is what the
-   * variables layer does everywhere.
-   *
-   * @param resolved - The recipe versions the resolution settled on.
-   * @param provided - Answers supplied ahead of the questions.
-   */
-  private async askVariables(
-    resolved: ResolvedRecipe[],
-    provided: ProvidedAnswer[]
-  ): Promise<AskReport | undefined> {
-    const defined = this.definedVariables(resolved);
-    if (defined.length === 0 && provided.length === 0) return undefined;
-
-    const context = this.ladderContext();
-    const options = {
-      sousDir: this.sousDir,
-      confDir: this.confDir,
-      interactive: this.interactive,
-    };
-
-    // A supplied answer naming a variable nothing declares fails here, before
-    // any question is asked and before anything is stored.
-    const supplied = applyProvidedAnswers(defined, provided, context, options);
-
-    const report = await askForMissing(defined, context, {
-      ...options,
-      skip: supplied.keys,
-    });
-    report.answered.unshift(...supplied.stored);
-    return report;
-  }
-}
-
-// --- Helpers ------------------------------------------------------------------------------------
-
-/**
- * Builds the subscription service for a running command, from what every
- * command already has: where its config was discovered, the merged settings,
- * and the shell environment as it was before the `.sous/` env files were loaded.
- *
- * @param options - The discovered config context, the settings, and the shell environment.
- */
-export function subscriptionServiceFor(options: {
-  /** Where the active config was found. */
-  configContext: ConfigContext;
-  /** The merged project config. */
-  settings: Settings;
-  /** The shell environment as it was before the env files were injected. */
-  shellEnv?: NodeJS.ProcessEnv;
-  /** Whether sous may ask questions. Defaults to whether both streams are a terminal. */
-  interactive?: boolean;
-}): SubscriptionService {
-  return new SubscriptionService({
-    sousDir: options.configContext.sousDir,
-    ...(options.configContext.confDir === undefined
-      ? {}
-      : { confDir: options.configContext.confDir }),
-    settings: options.settings,
-    ...(options.shellEnv === undefined ? {} : { shellEnv: options.shellEnv }),
-    ...(options.interactive === undefined ? {} : { interactive: options.interactive }),
-  });
-}
-
-/** One subscription entry, as it is written into the managed layer. */
-export type SubscriptionEntry = {
-  /**
-   * Whether the subscription takes part in anything. Defaults to true. Sous
-   * writes `false` when a subscription it provides itself is removed, because
-   * the default comes back on every run and only a recorded opt-out outlives it.
-   */
-  enabled?: boolean;
-  /** The semantic version range to resolve within. */
-  range?: string;
-  /** Whether prerelease versions take part in range matching. */
-  prerelease?: boolean;
-  /** Whether a newer in-range version is preferred over the locked one. */
-  alwaysPull?: boolean;
-  /** When the subscription was added. */
-  addedAt?: string;
-  /** Who required it: "user", or the ref of the recipe that co-subscribed it. */
-  addedBy?: string;
-};
-
-/**
- * Combines two resolutions of the SAME recipe version into one, so the lockfile
- * records every holder rather than only the last resolution's.
- *
- * This matters for removal: a recipe several subscriptions depend on has to
- * survive unsubscribing from one of them, and the lockfile's refcounting is what
- * decides that. A recipe anyone holds as a co-subscription is a co-subscription;
- * it is only a build dependency while nothing subscribes to it.
- *
- * @param left - The resolution already recorded.
- * @param right - The resolution to fold into it.
- */
-function mergeHolders(left: ResolvedRecipe, right: ResolvedRecipe): ResolvedRecipe {
-  const requestedBy = [...new Set([...left.requestedBy, ...right.requestedBy])].sort();
-
-  const ranges = [...left.ranges];
-  for (const entry of right.ranges) {
-    const known = ranges.some(
-      (seen) => seen.range === entry.range && seen.requestedBy === entry.requestedBy
-    );
-    if (!known) ranges.push(entry);
-  }
-
-  return {
-    ...left,
-    requestedBy,
-    ranges,
-    kind:
-      left.kind === "subscribes" || right.kind === "subscribes" ? "subscribes" : "depends",
-  };
-}
-
-/** The store key a resolved recipe is filed under. */
-function storeKeyFor(recipe: ResolvedRecipe): StoreKey {
-  return {
-    identity: recipe.identity,
-    namespace: recipe.namespace,
-    name: recipe.name,
-    version: recipe.version,
-  };
-}
-
-/** The message of an error, whichever kind it turned out to be. */
-function describeError(error: unknown): string {
-  if (isConfigError(error)) return (error as ConfigError).message;
-  return error instanceof Error ? error.message : String(error);
-}