@skrr-ai/cli 0.1.42 → 0.1.44

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/firstPartyHarness.js

@@ -24,25 +24,40 @@
  *      phase, once every peer accepts the new one;
  *   4. regenerate `first-party-harness.json`
  *      (`node --import tsx scripts/emit-first-party-harness-json.mjs`);
- *   5. ship the data migration, which is generic over `aliases`.
+ *   5. ship the data migration, which is generic over `aliases` and
+ *      `formerSpellings`;
+ *   6. at that rename's contract, move the spelling from `aliases` to the front
+ *      of `formerSpellings`.
  *
  * No identifier, file, env var name or workflow input moves.
  *
- * ── Three spellings, kept apart on purpose ────────────────────────────────
+ * ── Four fields, kept apart on purpose ────────────────────────────────────
  *
- * `provider`     CANONICAL. What the platform stores, returns and renders.
- * `aliases`      ACCEPTED on every ingress until contract, and normalised to
- *                canonical at the edge. Nothing new is ever written with one.
- * `wireProvider` What the server and a daemon say to EACH OTHER — the
- *                capability a daemon advertises, `daemon:<p>:request|response`,
- *                the `provider` of a session RPC. It moves after the flip and
- *                BEFORE contract, because a daemon on a user's machine may be
- *                any version and the server cannot tell which one sent a
- *                request: only a released daemon that already advertises the
- *                canonical capability lets the old one age out of the fleet.
+ * `provider`        CANONICAL. What the platform stores, returns and renders.
+ * `aliases`         ACCEPTED on every ingress during a rename's window, and
+ *                   normalised to canonical at the edge. Nothing new is ever
+ *                   written with one. Empty between renames.
+ * `formerSpellings` RETIRED. Accepted on NO ingress: no HTTP body, enum, Mongo
+ *                   filter, capability, wire event, CLI flag or trust table
+ *                   admits one. Recognised only where an ARTIFACT that predates
+ *                   the rename is read — a binary already installed, a checkout
+ *                   directory already on disk, a release already published
+ *                   under its prefix, a row or config key already written.
+ *                   Those exist whatever the platform accepts, and dropping a
+ *                   spelling from this list does not make them go away. Read it
+ *                   through `firstPartyHarnessArtifactSpellings`, never as an
+ *                   ingress check.
+ * `wireProvider`    What the server and a daemon say to EACH OTHER — the
+ *                   capability a daemon advertises,
+ *                   `daemon:<p>:request|response`, the `provider` of a session
+ *                   RPC. It moves after the flip and BEFORE contract, because a
+ *                   daemon on a user's machine may be any version and the
+ *                   server cannot tell which one sent a request: only a
+ *                   released daemon that already advertises the canonical
+ *                   capability lets the old one age out of the fleet.
  *
- * The old code treated those three as one string, which is why no single
- * change could rename it safely. See
+ * The old code treated these as one string, which is why no single change could
+ * rename it safely. See
  * `docs/architecture/skrr-code-identifier-rename-2026-09-13.md`.
  *
  * ── Constraints on this file ──────────────────────────────────────────────
@@ -56,38 +71,43 @@
 const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function defineIdentity(identity) {
     const spellings = [identity.provider, ...identity.aliases];
-    for (const spelling of spellings) {
+    const every = [...spellings, ...identity.formerSpellings];
+    for (const spelling of every) {
         if (!SLUG.test(spelling)) {
             throw new Error(`first-party harness spelling ${JSON.stringify(spelling)} is not a slug; it becomes a ` +
                 `directory name, a capability prefix and a wire event segment`);
         }
     }
-    if (new Set(spellings).size !== spellings.length) {
-        throw new Error('first-party harness provider and aliases must be distinct');
+    if (new Set(every).size !== every.length) {
+        throw new Error('first-party harness provider, aliases and formerSpellings must be distinct — a spelling ' +
+            'is accepted or retired, never both');
     }
     if (!spellings.includes(identity.wireProvider)) {
         throw new Error(`first-party harness wireProvider ${JSON.stringify(identity.wireProvider)} must be the ` +
             'provider or one of its aliases — a peer can only accept a spelling it knows');
     }
-    return Object.freeze({ ...identity, aliases: Object.freeze([...identity.aliases]) });
+    return Object.freeze({
+        ...identity,
+        aliases: Object.freeze([...identity.aliases]),
+        formerSpellings: Object.freeze([...identity.formerSpellings]),
+    });
 }
 /** The canonical slug. Written once, and read by every field that names the current spelling. */
 const PROVIDER = 'skrr-code';
 /**
  * THE identity — the only literal product name in the codebase.
  *
- * Phase: WIRE MOVED. `skrr-code` is canonical — stored, returned, rendered — and
- * it is now also what the server and a daemon say to each other. `sky-code` is
- * still accepted on every ingress, so a daemon released before this change
- * (which advertises and answers on `sky-code`) keeps working against a server
- * that speaks `skrr-code`, and the reverse. Contract (OSK-8663) empties
- * `aliases` once no connected daemon still advertises the old capability.
+ * Phase: CONTRACTED (OSK-8663). `skrr-code` is the only spelling any ingress
+ * accepts and the only one on the wire. `sky-code` is retired: nothing admits
+ * it, and it is still recognised where a binary, a checkout, a published
+ * release or a stored value written before the rename is looked for.
  */
 const IDENTITY = {
     displayName: 'skrr Code',
     command: 'skrr code',
     provider: PROVIDER,
-    aliases: ['sky-code'],
+    aliases: [],
+    formerSpellings: ['sky-code'],
     wireProvider: PROVIDER,
 };
 export const FIRST_PARTY_HARNESS = defineIdentity(IDENTITY);
@@ -98,6 +118,11 @@ const SPELLINGS = Object.freeze([
     ...FIRST_PARTY_HARNESS.aliases,
 ]);
 const SPELLING_SET = new Set(SPELLINGS);
+const ARTIFACT_SPELLINGS = Object.freeze([
+    ...SPELLINGS,
+    ...FIRST_PARTY_HARNESS.formerSpellings,
+]);
+const ARTIFACT_SPELLING_SET = new Set(ARTIFACT_SPELLINGS);
 const SESSION_SUFFIX = '_session';
 const ENVIRONMENT_PREFIX = 'local-';
 function asSlug(value) {
@@ -106,10 +131,30 @@ function asSlug(value) {
     const slug = value.trim().toLowerCase();
     return slug ? slug : null;
 }
-/** Every spelling, canonical first. The order is the resolution order. */
+/**
+ * Every ACCEPTED spelling, canonical first — what an ingress admits. The order
+ * is the resolution order.
+ */
 export function firstPartyHarnessSpellings() {
     return SPELLINGS;
 }
+/**
+ * Every spelling an ARTIFACT that already exists may carry, canonical first:
+ * the accepted spellings, then every former one.
+ *
+ * For code that LOOKS FOR what an earlier release left behind — an installed
+ * binary, a checkout directory, an immutable published release, a stored value
+ * or config key — and for the tooling that must keep recognising those
+ * (ignore lists, the identity ratchet). A machine that never ran a post-rename
+ * client still has its engine under the old name, and it must still be found.
+ *
+ * Never an ingress check: a former spelling is not accepted anywhere, and a
+ * reader that admitted one here would silently reopen what contract closed. Use
+ * `firstPartyHarnessSpellings` / `isFirstPartyHarnessProvider` for that.
+ */
+export function firstPartyHarnessArtifactSpellings() {
+    return ARTIFACT_SPELLINGS;
+}
 /** True for the canonical provider or any alias (case- and whitespace-insensitive). */
 export function isFirstPartyHarnessProvider(value) {
     const slug = asSlug(value);
@@ -123,6 +168,27 @@ export function isFirstPartyHarnessProvider(value) {
 export function canonicalHarnessProvider(value) {
     return isFirstPartyHarnessProvider(value) ? FIRST_PARTY_HARNESS.provider : value;
 }
+/**
+ * The canonical provider for a value read back from an ARTIFACT that may predate
+ * a rename — any artifact spelling (canonical, alias or FORMER) becomes the
+ * provider; every other value is returned unchanged.
+ *
+ * For values nobody migrates and nobody can refuse: a harness row's stored
+ * display NAME (the operator migration rewrites `provider`, never `name`), a
+ * daemon's config file, a harness session binding on a user's machine. Read raw
+ * after contract, each would name an unknown provider — a label that renders the
+ * retired name again, a local session silently running another backend, a live
+ * resume context reset as new — with no error anywhere.
+ *
+ * NEVER for anything a peer, a client or an operator SENDS, and never for a
+ * trust, dispatch or admission decision: a former spelling is accepted on no
+ * ingress, and canonicalising one here would reopen what contract closed. Use
+ * `canonicalHarnessProvider` for those.
+ */
+export function canonicalArtifactHarnessProvider(value) {
+    const slug = asSlug(value);
+    return slug !== null && ARTIFACT_SPELLING_SET.has(slug) ? FIRST_PARTY_HARNESS.provider : value;
+}
 /**
  * Every spelling a stored row for this provider may carry, canonical first —
  * for a Mongo `$in` filter while rows written before a flip still exist. Any
@@ -202,9 +268,18 @@ export function canonicalExecutionEnvironment(value) {
 export function firstPartyHarnessBinaryName(provider = FIRST_PARTY_HARNESS.provider, platform) {
     return platform === 'win32' ? `${provider}.exe` : provider;
 }
-/** Every binary file name, canonical first — the lookup order. */
+/**
+ * Every binary file name an install may carry, canonical first — the lookup
+ * order, and the names an install links to the canonical binary.
+ *
+ * Built from the ARTIFACT spellings, former ones included: binaries are
+ * artifacts. An engine installed before a rename is still on disk under its old
+ * name, and a platform CLI or daemon built before it still looks for that name,
+ * so resolvers try it and installers leave a link at it. Neither makes the
+ * spelling acceptable on any ingress.
+ */
 export function firstPartyHarnessBinaryNames(platform) {
-    return SPELLINGS.map((spelling) => firstPartyHarnessBinaryName(spelling, platform));
+    return ARTIFACT_SPELLINGS.map((spelling) => firstPartyHarnessBinaryName(spelling, platform));
 }
 /**
  * The engine home directory name under the skrr config root.
@@ -215,7 +290,8 @@ export function firstPartyHarnessBinaryNames(platform) {
  * the managed `AGENTS.md` from `<home>`. Deriving it from the provider would, on
  * a fresh install after a provider rename, create a second directory the engine
  * never reads — managed instructions would stop applying with no error. It moves
- * when the engine's namespace moves, and not before.
+ * when the engine's namespace moves, and not before; it did in OSK-8674, and
+ * `migrateFirstPartyHarnessHome` moves a home under a legacy name onto it.
  */
 export function firstPartyHarnessHomeDirname() {
     return FIRST_PARTY_HARNESS_ENGINE.appName;
@@ -233,7 +309,13 @@ export const FIRST_PARTY_HARNESS_FEED_ORIGIN = 'https://updates.oversky.ai';
 export function firstPartyHarnessFeedPrefix(provider = FIRST_PARTY_HARNESS.provider) {
     return `${provider}/`;
 }
-/** Every feed prefix, canonical first. Publishing writes all of them. */
+/**
+ * Every feed prefix a publish WRITES, canonical first: the accepted spellings.
+ *
+ * A former spelling's prefix still holds every release published under it, and
+ * those stay served — their artifact URLs are inside signed manifests — but
+ * nothing new is written there, so its channel pointers stop moving at contract.
+ */
 export function firstPartyHarnessFeedPrefixes() {
     return SPELLINGS.map((spelling) => firstPartyHarnessFeedPrefix(spelling));
 }
@@ -245,97 +327,195 @@ export function firstPartyHarnessStagingPrefix(provider = FIRST_PARTY_HARNESS.pr
 export function firstPartyHarnessDefaultFeedBase(provider = FIRST_PARTY_HARNESS.provider) {
     return `${FIRST_PARTY_HARNESS_FEED_ORIGIN}/${provider}`;
 }
-function envName(name, legacy) {
-    return Object.freeze({ name, legacy: Object.freeze([...legacy]) });
+function envName(name) {
+    return Object.freeze({ name });
 }
 /**
- * Every environment variable the platform reads for the first-party harness,
- * by purpose. The neutral name wins; a legacy name is read only when the neutral
- * one is unset or blank, because a variable set in an ECS task definition, a
- * user's shell or a LaunchAgent does not change when the code does.
+ * Every environment variable the PLATFORM reads for the first-party harness, by
+ * purpose, under one brand-neutral name each — so a product rename never renames
+ * one.
+ *
+ * The product-named variables these replaced were read second until contract
+ * (OSK-8663) and are not read at all now. The ENGINE's own variables are a
+ * different namespace (`FIRST_PARTY_HARNESS_ENGINE.env`): the fork reads them,
+ * so a platform reader that must agree with the engine consults the engine's
+ * names explicitly (`readFirstPartyHarnessEngineEnv`) — the engine home is the
+ * one case (`home` below).
  */
 export const FIRST_PARTY_HARNESS_ENV = Object.freeze({
     /** Absolute path to an engine binary, overriding resolution. */
-    path: envName('SKRR_FIRST_PARTY_HARNESS_PATH', ['OVERSKY_SKY_CODE_PATH']),
+    path: envName('SKRR_FIRST_PARTY_HARNESS_PATH'),
     /** Forces the CLI's managed-inference mode. */
-    managed: envName('SKRR_FIRST_PARTY_HARNESS_MANAGED', ['OVERSKY_SKY_CODE_MANAGED']),
+    managed: envName('SKRR_FIRST_PARTY_HARNESS_MANAGED'),
     /** Update channel. */
-    channel: envName('SKRR_FIRST_PARTY_HARNESS_CHANNEL', ['OVERSKY_SKY_CODE_CHANNEL']),
+    channel: envName('SKRR_FIRST_PARTY_HARNESS_CHANNEL'),
     /** Update-feed base URL override. */
-    updateFeedBase: envName('SKRR_FIRST_PARTY_HARNESS_UPDATE_FEED_BASE', [
-        'OVERSKY_SKY_CODE_UPDATE_FEED_BASE',
-    ]),
+    updateFeedBase: envName('SKRR_FIRST_PARTY_HARNESS_UPDATE_FEED_BASE'),
     /** Path to a file of development release keys. */
-    devKeys: envName('SKRR_FIRST_PARTY_HARNESS_DEV_KEYS', ['OVERSKY_SKY_CODE_DEV_KEYS']),
+    devKeys: envName('SKRR_FIRST_PARTY_HARNESS_DEV_KEYS'),
     /** Engine version the desktop build bundles. */
-    bundleVersion: envName('SKRR_FIRST_PARTY_HARNESS_BUNDLE_VERSION', ['OVERSKY_BUNDLE_SKY_CODE']),
-    /** Engine home override (the engine reads its own name too — see ENGINE env below). */
-    home: envName('SKRR_FIRST_PARTY_HARNESS_HOME', ['SKY_CODE_HOME']),
+    bundleVersion: envName('SKRR_FIRST_PARTY_HARNESS_BUNDLE_VERSION'),
+    /**
+     * Engine home override. The engine reads only its own variable, under every
+     * name it has had (`readFirstPartyHarnessEngineEnv(env, 'home')`), so a reader
+     * that resolves the home the engine will use reads those second, and a
+     * launcher hands the engine the resolved path under every one of them
+     * (`firstPartyHarnessEngineEnvEntries`).
+     */
+    home: envName('SKRR_FIRST_PARTY_HARNESS_HOME'),
     /** Engine version baked into the cloud-coding image. */
-    cloudCodingVersion: envName('CLOUD_CODING_FIRST_PARTY_HARNESS_VERSION', [
-        'CLOUD_CODING_SKY_CODE_VERSION',
-    ]),
+    cloudCodingVersion: envName('CLOUD_CODING_FIRST_PARTY_HARNESS_VERSION'),
     /** Engine version baked into the Dedicated Runtime AMI. */
-    dedicatedRuntimeVersion: envName('SKRR_DEDICATED_RUNTIME_FIRST_PARTY_HARNESS_VERSION', [
-        'SKRR_DEDICATED_RUNTIME_SKY_CODE_VERSION',
-    ]),
+    dedicatedRuntimeVersion: envName('SKRR_DEDICATED_RUNTIME_FIRST_PARTY_HARNESS_VERSION'),
     /** Engine version the desktop release workflow bundles. */
-    desktopBundledVersion: envName('DESKTOP_BUNDLED_FIRST_PARTY_HARNESS_VERSION', [
-        'DESKTOP_BUNDLED_SKY_CODE_VERSION',
-    ]),
+    desktopBundledVersion: envName('DESKTOP_BUNDLED_FIRST_PARTY_HARNESS_VERSION'),
     /** Update-feed bucket used by publish and promote. */
-    updatesBucket: envName('FIRST_PARTY_HARNESS_UPDATES_BUCKET', ['SKY_CODE_UPDATES_BUCKET']),
+    updatesBucket: envName('FIRST_PARTY_HARNESS_UPDATES_BUCKET'),
     /** Release signing key (CI secret). */
-    signingKey: envName('FIRST_PARTY_HARNESS_SIGNING_KEY', ['SKY_CODE_SIGNING_KEY']),
+    signingKey: envName('FIRST_PARTY_HARNESS_SIGNING_KEY'),
     /** Release signing key id (CI secret). */
-    signingKeyId: envName('FIRST_PARTY_HARNESS_SIGNING_KEY_ID', ['SKY_CODE_SIGNING_KEY_ID']),
+    signingKeyId: envName('FIRST_PARTY_HARNESS_SIGNING_KEY_ID'),
 });
-/** Every name for one purpose, neutral first — for spawn-env forwarding and sanitisers. */
-export function firstPartyHarnessEnvNames(key) {
-    const entry = FIRST_PARTY_HARNESS_ENV[key];
-    return [entry.name, ...entry.legacy];
-}
-/** Read one purpose's variable: neutral name first, legacy names after. */
+/** Read one purpose's variable. A blank value counts as unset. */
 export function readFirstPartyHarnessEnv(env, key) {
-    const entry = FIRST_PARTY_HARNESS_ENV[key];
-    for (const name of [entry.name, ...entry.legacy]) {
-        const raw = env[name];
-        if (typeof raw === 'string' && raw.trim() !== '') {
-            return { value: raw.trim(), name, legacy: name !== entry.name };
-        }
+    const { name } = FIRST_PARTY_HARNESS_ENV[key];
+    const raw = env[name];
+    if (typeof raw === 'string' && raw.trim() !== '') {
+        return { value: raw.trim(), name };
     }
-    return { value: undefined, name: undefined, legacy: false };
+    return { value: undefined, name: undefined };
 }
 /* ── The ENGINE's own namespace (defined inside the fork) ───────────────── */
+/**
+ * The engine's state namespace today. Moved from `sky-code` by OSK-8674: XDG
+ * dirs, project directory, config basename, the engine home under the skrr
+ * root, and every variable the engine reads all derive from it.
+ */
+const ENGINE_APP_NAME = 'skrr-code';
+/**
+ * Earlier engine namespaces, newest first. Still READ on both sides of the
+ * daemon↔engine boundary: an engine binary, a daemon, a CLI and a desktop app
+ * each ship on their own schedule, and a machine holds state written under
+ * every name it has run.
+ */
+const ENGINE_LEGACY_APP_NAMES = ['sky-code'];
+/**
+ * Every variable the engine reads, by purpose, as the suffix after the app
+ * name's prefix (`skrr-code` → `SKRR_CODE_<suffix>`). The fork names all of its
+ * own variables this way, so the names follow the namespace rather than being
+ * written out once per spelling.
+ */
+const ENGINE_ENV_SUFFIXES = Object.freeze({
+    serverPassword: 'SERVER_PASSWORD',
+    serverUsername: 'SERVER_USERNAME',
+    home: 'HOME',
+    config: 'CONFIG',
+    appName: 'APP_NAME',
+    scriptName: 'SCRIPT_NAME',
+    allowUpstreamEgress: 'ALLOW_UPSTREAM_EGRESS',
+    compatOpencode: 'COMPAT_OPENCODE',
+    noCompatPrompts: 'NO_COMPAT_PROMPTS',
+});
+function engineEnvName(appName, key) {
+    return `${appName.toUpperCase().replace(/-/g, '_')}_${ENGINE_ENV_SUFFIXES[key]}`;
+}
+function engineEnvTable(appName) {
+    return Object.freeze(Object.fromEntries(Object.keys(ENGINE_ENV_SUFFIXES).map((key) => [
+        key,
+        engineEnvName(appName, key),
+    ])));
+}
+function defineEngineNamespace(appName, legacyAppNames) {
+    const every = [appName, ...legacyAppNames];
+    for (const name of every) {
+        if (!SLUG.test(name)) {
+            throw new Error(`first-party harness engine app name ${JSON.stringify(name)} is not a slug; it becomes a ` +
+                'directory name and a variable prefix');
+        }
+    }
+    if (new Set(every).size !== every.length) {
+        throw new Error('first-party harness engine appName and legacyAppNames must be distinct');
+    }
+    return Object.freeze({
+        /**
+         * The engine's state namespace: XDG dirs, project marker, config basename, and
+         * the engine home under the skrr root (`firstPartyHarnessHomeDirname`).
+         */
+        appName,
+        /**
+         * Earlier `appName`s, newest first. `migrateFirstPartyHarnessHome` moves a home
+         * under one of them onto the current name and leaves a symlink; readers of
+         * engine state look under them after the current name.
+         */
+        legacyAppNames: Object.freeze([...legacyAppNames]),
+        /** Project-local configuration directory inside a user's repository. */
+        projectDirectory: `.${appName}`,
+        /**
+         * Earlier project directories, newest first. The engine still reads them and
+         * the platform never rewrites a user's repository to move one, so a reader
+         * looks here after `projectDirectory`, and a writer adopts an existing file
+         * here rather than creating a second one beside it.
+         */
+        legacyProjectDirectories: Object.freeze(legacyAppNames.map((name) => `.${name}`)),
+        /**
+         * Environment variables the engine reads, under the CURRENT namespace. The
+         * engine also reads each one under every legacy namespace, second — use
+         * `readFirstPartyHarnessEngineEnv` to read one the way the engine does and
+         * `firstPartyHarnessEngineEnvEntries` to set one every engine build honours.
+         */
+        env: engineEnvTable(appName),
+    });
+}
 /**
  * Names the ENGINE itself defines and reads. The platform sets or reads them
  * across the daemon↔engine boundary, so they are recorded here as values rather
- * than scattered as literals — but they are the fork's to change, and moving
- * one is a two-sided change (contract §6). Not part of this identity's rename.
+ * than scattered as literals. They are the fork's names, and moving one is a
+ * two-sided change: the engine reads the new name first and every legacy name
+ * second, and while engine and platform releases can arrive in either order the
+ * platform SETS every name and READS new-then-legacy (contract §6, OSK-8674).
  */
-export const FIRST_PARTY_HARNESS_ENGINE = Object.freeze({
-    /**
-     * The engine's state namespace: XDG dirs, project marker, config basename, and
-     * the engine home under the skrr root (`firstPartyHarnessHomeDirname`).
-     */
-    appName: 'sky-code',
-    /**
-     * Earlier `appName`s whose home directory `migrateFirstPartyHarnessHome` moves
-     * onto the current one. Empty until the engine's namespace is renamed.
-     */
-    legacyAppNames: Object.freeze([]),
-    /** Project-local configuration directory inside a user's repository. */
-    projectDirectory: '.sky-code',
-    /** Environment variables the engine reads. */
-    env: Object.freeze({
-        serverPassword: 'SKY_CODE_SERVER_PASSWORD',
-        serverUsername: 'SKY_CODE_SERVER_USERNAME',
-        home: 'SKY_CODE_HOME',
-        config: 'SKY_CODE_CONFIG',
-        appName: 'SKY_CODE_APP_NAME',
-        scriptName: 'SKY_CODE_SCRIPT_NAME',
-        allowUpstreamEgress: 'SKY_CODE_ALLOW_UPSTREAM_EGRESS',
-        compatOpencode: 'SKY_CODE_COMPAT_OPENCODE',
-        noCompatPrompts: 'SKY_CODE_NO_COMPAT_PROMPTS',
-    }),
-});
+export const FIRST_PARTY_HARNESS_ENGINE = defineEngineNamespace(ENGINE_APP_NAME, ENGINE_LEGACY_APP_NAMES);
+/**
+ * Every name the engine reads for one purpose, current namespace first — the
+ * engine's own lookup order.
+ */
+export function firstPartyHarnessEngineEnvNames(key) {
+    return [FIRST_PARTY_HARNESS_ENGINE.appName, ...FIRST_PARTY_HARNESS_ENGINE.legacyAppNames].map((appName) => engineEnvName(appName, key));
+}
+/**
+ * Read one engine variable the way the engine reads it: the current name, then
+ * every legacy name. A blank value counts as unset.
+ */
+export function readFirstPartyHarnessEngineEnv(env, key) {
+    for (const name of firstPartyHarnessEngineEnvNames(key)) {
+        const raw = env[name];
+        if (typeof raw === 'string' && raw.trim() !== '') {
+            return { value: raw.trim(), name };
+        }
+    }
+    return { value: undefined, name: undefined };
+}
+/**
+ * One engine variable set under EVERY name the engine has read, for a process
+ * that spawns the engine. An engine binary is installed on its own schedule, so
+ * a launcher cannot know whether the one it starts reads the current name or a
+ * legacy one; setting both means either build receives the value.
+ */
+export function firstPartyHarnessEngineEnvEntries(key, value) {
+    return Object.fromEntries(firstPartyHarnessEngineEnvNames(key).map((name) => [name, value]));
+}
+/** Every engine project directory, current first — the engine's read order. */
+export function firstPartyHarnessEngineProjectDirectories() {
+    return [
+        FIRST_PARTY_HARNESS_ENGINE.projectDirectory,
+        ...FIRST_PARTY_HARNESS_ENGINE.legacyProjectDirectories,
+    ];
+}
+/**
+ * Every engine home directory name under a config root, current first: where an
+ * engine home may exist on disk. `firstPartyHarnessHomeDirname` is the one the
+ * platform writes.
+ */
+export function firstPartyHarnessEngineHomeDirnames() {
+    return [FIRST_PARTY_HARNESS_ENGINE.appName, ...FIRST_PARTY_HARNESS_ENGINE.legacyAppNames];
+}

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/firstPartyHarnessChannels.d.ts

@@ -108,40 +108,28 @@ export interface FirstPartyHarnessFeedCandidate {
  * Every place a manifest may be published, in the order an installer should
  * try them: the canonical spelling first, then each alias.
  *
- * Why a list: publishing writes every spelling, but an installer can ship before
- * the first release that does, and a machine can point at a feed published by
- * an older pipeline. An installer that asked only for the canonical path would
- * then find NOTHING and report "no release" on a feed that has one. Trying the
- * aliases on not-found closes that window in both directions without anyone
- * having to deploy in a particular order.
+ * Why a list: publishing writes every accepted spelling, but an installer can
+ * ship before the first release that does, and a machine can point at a feed
+ * published by an older pipeline. An installer that asked only for the canonical
+ * path would then find NOTHING and report "no release" on a feed that has one.
+ * Trying the aliases on not-found closes that window in both directions without
+ * anyone having to deploy in a particular order.
+ *
+ * WHICH spellings depends on what is being read, and the difference is the
+ * point:
+ *
+ *   - a CHANNEL pointer (`pinnedRelease` false) is current state. Only the
+ *     accepted spellings are tried: a former spelling's pointer stopped moving
+ *     when publishing stopped writing it, so falling back to one would install
+ *     whatever that channel named on the day of contract — a silent downgrade.
+ *   - a PINNED release (`pinnedRelease` true) is an immutable artifact. Former
+ *     spellings are tried too: a release published before the canonical prefix
+ *     existed lives only under the old one, and its signed bytes — artifact URLs
+ *     included — are the same wherever they are found.
  *
  * An operator override keeps its base and still tries each manifest filename,
  * since a dev feed staged by an older script names the file the old way.
  */
-export declare function firstPartyHarnessFeedCandidates(env?: NodeJS.ProcessEnv): readonly FirstPartyHarnessFeedCandidate[];
-/** @deprecated Use `FIRST_PARTY_HARNESS_CHANNELS`. */
-export declare const SKY_CODE_CHANNELS: readonly ["internal", "canary", "beta", "stable"];
-/** @deprecated Use `FirstPartyHarnessChannel`. */
-export type SkyCodeChannel = FirstPartyHarnessChannel;
-/** @deprecated Use `DEFAULT_FIRST_PARTY_HARNESS_CHANNEL`. */
-export declare const DEFAULT_SKY_CODE_CHANNEL: "stable";
-/** @deprecated Read the channel with `resolveFirstPartyHarnessChannel`; the variable has a neutral name now. */
-export declare const SKY_CODE_CHANNEL_ENV: string;
-/** @deprecated Use `firstPartyHarnessManifestFile()`. Names the legacy file. */
-export declare const SKY_CODE_MANIFEST_FILE: string;
-/** @deprecated Use `isFirstPartyHarnessChannel`. */
-export declare const isSkyCodeChannel: typeof isFirstPartyHarnessChannel;
-/** @deprecated Use `resolveFirstPartyHarnessChannel`. */
-export declare const resolveSkyCodeChannel: typeof resolveFirstPartyHarnessChannel;
-/** @deprecated Use `firstPartyHarnessChannelPrefix`. */
-export declare const skyCodeChannelPrefix: typeof firstPartyHarnessChannelPrefix;
-/** @deprecated Use `firstPartyHarnessDefaultFeedBase()`. Names the legacy feed. */
-export declare const DEFAULT_SKY_CODE_FEED_BASE: string;
-/** @deprecated Read the feed with `firstPartyHarnessFeedBase`; the variable has a neutral name now. */
-export declare const SKY_CODE_FEED_BASE_ENV: string;
-/**
- * @deprecated Use `firstPartyHarnessFeedCandidates`. Keeps the LEGACY feed as its
- * default, because that is the only feed a caller compiled against this name knows
- * how to read.
- */
-export declare function skyCodeFeedBase(env?: NodeJS.ProcessEnv): string;
+export declare function firstPartyHarnessFeedCandidates(env?: NodeJS.ProcessEnv, options?: {
+    pinnedRelease?: boolean;
+}): readonly FirstPartyHarnessFeedCandidate[];

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/firstPartyHarnessChannels.js

@@ -26,7 +26,7 @@
  * Every product-named value comes from `firstPartyHarness.ts`; nothing in this
  * file spells the product.
  */
-import { FIRST_PARTY_HARNESS, FIRST_PARTY_HARNESS_ENV, firstPartyHarnessDefaultFeedBase, firstPartyHarnessManifestFile, firstPartyHarnessSpellings, readFirstPartyHarnessEnv, } from './firstPartyHarness.js';
+import { firstPartyHarnessArtifactSpellings, firstPartyHarnessDefaultFeedBase, firstPartyHarnessManifestFile, firstPartyHarnessSpellings, readFirstPartyHarnessEnv, } from './firstPartyHarness.js';
 /** Channels in promotion order. Index order IS the promotion order. */
 export const FIRST_PARTY_HARNESS_CHANNELS = ['internal', 'canary', 'beta', 'stable'];
 /**
@@ -116,61 +116,36 @@ export function firstPartyHarnessFeedBase(env = process.env) {
  * Every place a manifest may be published, in the order an installer should
  * try them: the canonical spelling first, then each alias.
  *
- * Why a list: publishing writes every spelling, but an installer can ship before
- * the first release that does, and a machine can point at a feed published by
- * an older pipeline. An installer that asked only for the canonical path would
- * then find NOTHING and report "no release" on a feed that has one. Trying the
- * aliases on not-found closes that window in both directions without anyone
- * having to deploy in a particular order.
+ * Why a list: publishing writes every accepted spelling, but an installer can
+ * ship before the first release that does, and a machine can point at a feed
+ * published by an older pipeline. An installer that asked only for the canonical
+ * path would then find NOTHING and report "no release" on a feed that has one.
+ * Trying the aliases on not-found closes that window in both directions without
+ * anyone having to deploy in a particular order.
+ *
+ * WHICH spellings depends on what is being read, and the difference is the
+ * point:
+ *
+ *   - a CHANNEL pointer (`pinnedRelease` false) is current state. Only the
+ *     accepted spellings are tried: a former spelling's pointer stopped moving
+ *     when publishing stopped writing it, so falling back to one would install
+ *     whatever that channel named on the day of contract — a silent downgrade.
+ *   - a PINNED release (`pinnedRelease` true) is an immutable artifact. Former
+ *     spellings are tried too: a release published before the canonical prefix
+ *     existed lives only under the old one, and its signed bytes — artifact URLs
+ *     included — are the same wherever they are found.
  *
  * An operator override keeps its base and still tries each manifest filename,
  * since a dev feed staged by an older script names the file the old way.
  */
-export function firstPartyHarnessFeedCandidates(env = process.env) {
+export function firstPartyHarnessFeedCandidates(env = process.env, options = {}) {
     const override = readFirstPartyHarnessEnv(env, 'updateFeedBase').value?.replace(/\/+$/, '');
-    return firstPartyHarnessSpellings().map((provider) => ({
+    const spellings = options.pinnedRelease
+        ? firstPartyHarnessArtifactSpellings()
+        : firstPartyHarnessSpellings();
+    return spellings.map((provider) => ({
         base: override || firstPartyHarnessDefaultFeedBase(provider),
         manifestFilename: firstPartyHarnessManifestFile(provider),
         provider,
     }));
 }
-/* ── Deprecated names ───────────────────────────────────────────────────────
- *
- * `@skrr-ai/auth-core` is PUBLISHED, and the released CLI resolves it with a
- * caret range. An installed CLI that picks up this version must still find the
- * names it was compiled against, or it crashes at import. These aliases leave in
- * the contract phase (OSK-8663), with a minor-version bump — never a patch.
- *
- * The ones that name a feed name the LEGACY one, the spelling a caller compiled
- * against them was built for — the retired alias, not `wireProvider`, which has
- * moved to canonical.
- */
-/** The spelling the deprecated names were written for. */
-const LEGACY_SPELLING = FIRST_PARTY_HARNESS.aliases[0] ?? FIRST_PARTY_HARNESS.provider;
-/** @deprecated Use `FIRST_PARTY_HARNESS_CHANNELS`. */
-export const SKY_CODE_CHANNELS = FIRST_PARTY_HARNESS_CHANNELS;
-/** @deprecated Use `DEFAULT_FIRST_PARTY_HARNESS_CHANNEL`. */
-export const DEFAULT_SKY_CODE_CHANNEL = DEFAULT_FIRST_PARTY_HARNESS_CHANNEL;
-/** @deprecated Read the channel with `resolveFirstPartyHarnessChannel`; the variable has a neutral name now. */
-export const SKY_CODE_CHANNEL_ENV = FIRST_PARTY_HARNESS_ENV.channel.legacy[0];
-/** @deprecated Use `firstPartyHarnessManifestFile()`. Names the legacy file. */
-export const SKY_CODE_MANIFEST_FILE = firstPartyHarnessManifestFile(LEGACY_SPELLING);
-/** @deprecated Use `isFirstPartyHarnessChannel`. */
-export const isSkyCodeChannel = isFirstPartyHarnessChannel;
-/** @deprecated Use `resolveFirstPartyHarnessChannel`. */
-export const resolveSkyCodeChannel = resolveFirstPartyHarnessChannel;
-/** @deprecated Use `firstPartyHarnessChannelPrefix`. */
-export const skyCodeChannelPrefix = firstPartyHarnessChannelPrefix;
-/** @deprecated Use `firstPartyHarnessDefaultFeedBase()`. Names the legacy feed. */
-export const DEFAULT_SKY_CODE_FEED_BASE = firstPartyHarnessDefaultFeedBase(LEGACY_SPELLING);
-/** @deprecated Read the feed with `firstPartyHarnessFeedBase`; the variable has a neutral name now. */
-export const SKY_CODE_FEED_BASE_ENV = FIRST_PARTY_HARNESS_ENV.updateFeedBase.legacy[0];
-/**
- * @deprecated Use `firstPartyHarnessFeedCandidates`. Keeps the LEGACY feed as its
- * default, because that is the only feed a caller compiled against this name knows
- * how to read.
- */
-export function skyCodeFeedBase(env = process.env) {
-    const override = readFirstPartyHarnessEnv(env, 'updateFeedBase').value;
-    return (override || firstPartyHarnessDefaultFeedBase(LEGACY_SPELLING)).replace(/\/+$/, '');
-}