@skrr-ai/cli 0.1.32 → 0.1.34

package/dist/lib/{sky-code-managed.d.ts → first-party-harness-managed.d.ts}

@@ -1,7 +1,7 @@
 /**
- * OSK-3892 — the DECISION half of a CLI-hosted managed skrr Code session.
+ * OSK-3892 — the DECISION half of a CLI-hosted managed first-party harness session.
  *
- * skrr Code is standalone-capable and daemon-preferred: when a daemon is in the
+ * The first-party harness is standalone-capable and daemon-preferred: when a daemon is in the
  * loop it brokers inference, and when a human just ran `skrr login` the CLI hosts
  * the broker itself. This module answers the two questions that must be answered
  * BEFORE any credential exists —
@@ -17,9 +17,9 @@
  * Everything here is pure (env, a config read, one `existsSync`) and imports no
  * auth, no data-provider and no broker. That is what lets `skrr code doctor` report
  * the posture without configuring the auth plane, and it keeps
- * `sky-code-doctor.ts` honest about being safe to run in any context. The
+ * `first-party-harness-doctor.ts` honest about being safe to run in any context. The
  * acquisition and the `execEngine` hooks that drive it live in
- * `sky-code-broker.ts`, which the `skrr code` commands import directly.
+ * `first-party-harness-broker.ts`, which the `skrr code` commands import directly.
  *
  * ── Invariant I4: managed / BYOK / offline never silently become each other ─
  *
@@ -30,21 +30,14 @@
  * once, on stderr. Acquisition failures are always announced, for the same
  * reason: the user is about to spend their own key and must know it.
  */
-/**
- * Opt OUT of a CLI-hosted managed session.
- *
- * Present because "run with my own key" has to be expressible without logging
- * out, and because a test that asserts argv forwarding must be able to say "this
- * run is not about acquisition" rather than depend on whether the machine
- * happens to be signed in.
- */
-export declare const MANAGED_ENV_FLAG = "OVERSKY_SKY_CODE_MANAGED";
+/** The neutral operator switch for CLI-hosted managed inference. */
+export declare const MANAGED_ENV_FLAG: string;
 /**
  * The CLI's own flag, deliberately NOT `--agent`.
  *
  * `skrr code` forwards argv VERBATIM and the engine owns the bare flag namespace —
  * `skrr code --agent reviewer` is the engine's flag and is pinned as such by
- * `sky-code-passthrough.spec.ts`. A bare `--agent` here would steal it.
+ * `first-party-harness-passthrough.spec.ts`. A bare `--agent` here would steal it.
  */
 export declare const SKRR_AGENT_FLAG = "--skrr-agent";
 /**
@@ -59,26 +52,58 @@ export declare const SKRR_AGENT_FLAG = "--skrr-agent";
 export declare const OVERSKY_AGENT_FLAG = "--oversky-agent";
 /** Every spelling the argv scanner honours, primary first. */
 export declare const AGENT_FLAG_SPELLINGS: readonly ["--skrr-agent", "--oversky-agent"];
-/** The config key `skrr code` reads when the flag is absent. */
-export declare const AGENT_CONFIG_KEY = "skyCodeAgentId";
 /**
- * The harness name this CLI is, as the server spells it.
- *
- * The server never takes it from the wire — `sessionInferenceRelay.js` fixes
- * `provider: 'sky-code'` itself, because it selects the relay capability and
- * composes the `provider_model` budget key, none of which is a caller's choice.
- * So this is not a request parameter; it is the CLI naming itself in the two
- * places that legitimately ask (the trust-tier lookup, and which default agent
- * to establish).
+ * The config key `skrr code` reads when the flag is absent — and writes.
+ *
+ * Brand-neutral, so a product rename never moves it. Earlier CLIs stored the same
+ * setting under a key named after the product; those are still READ
+ * ({@link legacyAgentConfigKeys}), and every write replaces them with this one.
+ *
+ * The harness name the CLI sends when it asks for a default agent is not a
+ * constant here at all: it is `FIRST_PARTY_HARNESS.provider`. The server never
+ * takes the managed-session provider from the wire — `sessionInferenceRelay.js`
+ * fixes it itself, because it selects the relay capability and composes the
+ * `provider_model` budget key, none of which is a caller's choice — so the CLI
+ * names itself only where that legitimately matters (the trust-tier lookup, and
+ * which default agent to establish).
+ */
+export declare const AGENT_CONFIG_KEY: "firstPartyHarnessAgentId";
+/**
+ * Keys earlier CLIs stored the agent setting under: `<camelCased spelling>AgentId`
+ * for every spelling of the harness, canonical first.
+ *
+ * Derived rather than listed so no product name is written here — and so the key
+ * is read for exactly as long as its spelling is accepted anywhere else.
+ */
+export declare function legacyAgentConfigKeys(): string[];
+export interface AgentSetting {
+    /** Trimmed, non-empty value, or undefined when nothing usable is stored. */
+    value: string | undefined;
+    /** The key that supplied `value`. */
+    key: string | undefined;
+    /** True when `key` is an older name for the setting. */
+    legacy: boolean;
+}
+/** Read the setting from a config record: the neutral key first, then each older key. */
+export declare function readAgentSetting(config: Readonly<Record<string, unknown>>): AgentSetting;
+/**
+ * The setting as the effective config holds it. THROWS when the config file is
+ * unparseable, exactly as `loadConfig` does — callers that must not fail catch it.
+ */
+export declare function readConfiguredAgentSetting(): AgentSetting;
+/**
+ * A copy of `raw` with the setting written under the neutral key (or removed when
+ * `id` is undefined) and EVERY older key removed — so a later read can never find a
+ * stale value under a name this write did not touch.
  */
-export declare const SKY_CODE_HARNESS = "sky-code";
+export declare function withAgentSetting(raw: Readonly<Record<string, unknown>>, id: string | undefined): Record<string, unknown>;
 /**
  * Mirrored from `@skrr-ai/inference-broker`, for the same reason
  * `harness-tiers.ts` mirrors the daemon's trust table: importing the package
  * would pull a loopback SERVER into `skrr code doctor` and into every unmanaged
  * `skrr code` startup, to read two string constants.
  *
- * `sky-code-managed.spec.ts` asserts these against the package, so a rename there
+ * `first-party-harness-managed.spec.ts` asserts these against the package, so a rename there
  * fails a test here rather than silently making the posture check blind.
  */
 export declare const MANAGED_SESSION_ENV = "OVERSKY_MANAGED_SESSION";
@@ -103,8 +128,8 @@ export declare const MANAGED_SESSION_ENV = "OVERSKY_MANAGED_SESSION";
  * CLI-hosted broker cannot forge the first pair, which is what makes the order
  * load-bearing rather than stylistic.
  */
-export type SkyCodeTrustPlane = 'daemon-supervised' | 'cli-brokered' | 'standalone';
-export declare function resolveTrustPlane(env: NodeJS.ProcessEnv): SkyCodeTrustPlane;
+export type EngineTrustPlane = 'daemon-supervised' | 'cli-brokered' | 'standalone';
+export declare function resolveTrustPlane(env: NodeJS.ProcessEnv): EngineTrustPlane;
 export declare const BROKER_SOCKET_ENV = "OVERSKY_INFERENCE_BROKER_SOCKET";
 export type ManagedSkipKind = 'disabled' | 'daemon-brokered' | 'unsupported-platform' | 'insecure-server';
 export interface ManagedSkip {
@@ -125,7 +150,7 @@ export interface ManagedSkip {
  * posture computed from the real `process.env` while claiming to describe the
  * supplied one is a diagnostic that lies.
  */
-export declare function skyCodeServerUrl(env?: NodeJS.ProcessEnv): string;
+export declare function configuredServerUrl(env?: NodeJS.ProcessEnv): string;
 /**
  * Why this process would NOT host a managed session — or `null` if it would.
  *
@@ -142,7 +167,7 @@ export declare function managedSkipReason(env?: NodeJS.ProcessEnv): ManagedSkip
  * or not this run ends up brokering. Both spellings are accepted, and the
  * space-separated form consumes its value token.
  *
- * Everything else is spliced out IN PLACE: `sky-code-passthrough.spec.ts` asserts
+ * Everything else is spliced out IN PLACE: `first-party-harness-passthrough.spec.ts` asserts
  * exact array equality, so order and adjacency are the contract, and a flag
  * separated from its value is a different command.
  */

package/dist/lib/{sky-code-managed.js → first-party-harness-managed.js}

@@ -1,8 +1,8 @@
 "use strict";
 /**
- * OSK-3892 — the DECISION half of a CLI-hosted managed skrr Code session.
+ * OSK-3892 — the DECISION half of a CLI-hosted managed first-party harness session.
  *
- * skrr Code is standalone-capable and daemon-preferred: when a daemon is in the
+ * The first-party harness is standalone-capable and daemon-preferred: when a daemon is in the
  * loop it brokers inference, and when a human just ran `skrr login` the CLI hosts
  * the broker itself. This module answers the two questions that must be answered
  * BEFORE any credential exists —
@@ -18,9 +18,9 @@
  * Everything here is pure (env, a config read, one `existsSync`) and imports no
  * auth, no data-provider and no broker. That is what lets `skrr code doctor` report
  * the posture without configuring the auth plane, and it keeps
- * `sky-code-doctor.ts` honest about being safe to run in any context. The
+ * `first-party-harness-doctor.ts` honest about being safe to run in any context. The
  * acquisition and the `execEngine` hooks that drive it live in
- * `sky-code-broker.ts`, which the `skrr code` commands import directly.
+ * `first-party-harness-broker.ts`, which the `skrr code` commands import directly.
  *
  * ── Invariant I4: managed / BYOK / offline never silently become each other ─
  *
@@ -32,32 +32,30 @@
  * reason: the user is about to spend their own key and must know it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BROKER_SOCKET_ENV = exports.MANAGED_SESSION_ENV = exports.SKY_CODE_HARNESS = exports.AGENT_CONFIG_KEY = exports.AGENT_FLAG_SPELLINGS = exports.OVERSKY_AGENT_FLAG = exports.SKRR_AGENT_FLAG = exports.MANAGED_ENV_FLAG = void 0;
+exports.BROKER_SOCKET_ENV = exports.MANAGED_SESSION_ENV = exports.AGENT_CONFIG_KEY = exports.AGENT_FLAG_SPELLINGS = exports.OVERSKY_AGENT_FLAG = exports.SKRR_AGENT_FLAG = exports.MANAGED_ENV_FLAG = void 0;
+exports.legacyAgentConfigKeys = legacyAgentConfigKeys;
+exports.readAgentSetting = readAgentSetting;
+exports.readConfiguredAgentSetting = readConfiguredAgentSetting;
+exports.withAgentSetting = withAgentSetting;
 exports.resolveTrustPlane = resolveTrustPlane;
-exports.skyCodeServerUrl = skyCodeServerUrl;
+exports.configuredServerUrl = configuredServerUrl;
 exports.managedSkipReason = managedSkipReason;
 exports.takeOverskyAgentFlag = takeOverskyAgentFlag;
 exports.namedEngineModel = namedEngineModel;
 exports.withManagedModel = withManagedModel;
 exports.managedInferencePosture = managedInferencePosture;
 const node_fs_1 = require("node:fs");
+const auth_core_1 = require("@skrr-ai/auth-core");
 const config_1 = require("./config");
 const runtime_context_1 = require("./runtime-context");
-/**
- * Opt OUT of a CLI-hosted managed session.
- *
- * Present because "run with my own key" has to be expressible without logging
- * out, and because a test that asserts argv forwarding must be able to say "this
- * run is not about acquisition" rather than depend on whether the machine
- * happens to be signed in.
- */
-exports.MANAGED_ENV_FLAG = 'OVERSKY_SKY_CODE_MANAGED';
+/** The neutral operator switch for CLI-hosted managed inference. */
+exports.MANAGED_ENV_FLAG = auth_core_1.FIRST_PARTY_HARNESS_ENV.managed.name;
 /**
  * The CLI's own flag, deliberately NOT `--agent`.
  *
  * `skrr code` forwards argv VERBATIM and the engine owns the bare flag namespace —
  * `skrr code --agent reviewer` is the engine's flag and is pinned as such by
- * `sky-code-passthrough.spec.ts`. A bare `--agent` here would steal it.
+ * `first-party-harness-passthrough.spec.ts`. A bare `--agent` here would steal it.
  */
 exports.SKRR_AGENT_FLAG = '--skrr-agent';
 /**
@@ -72,26 +70,77 @@ exports.SKRR_AGENT_FLAG = '--skrr-agent';
 exports.OVERSKY_AGENT_FLAG = '--oversky-agent';
 /** Every spelling the argv scanner honours, primary first. */
 exports.AGENT_FLAG_SPELLINGS = [exports.SKRR_AGENT_FLAG, exports.OVERSKY_AGENT_FLAG];
-/** The config key `skrr code` reads when the flag is absent. */
-exports.AGENT_CONFIG_KEY = 'skyCodeAgentId';
 /**
- * The harness name this CLI is, as the server spells it.
+ * The config key `skrr code` reads when the flag is absent — and writes.
  *
- * The server never takes it from the wire — `sessionInferenceRelay.js` fixes
- * `provider: 'sky-code'` itself, because it selects the relay capability and
- * composes the `provider_model` budget key, none of which is a caller's choice.
- * So this is not a request parameter; it is the CLI naming itself in the two
- * places that legitimately ask (the trust-tier lookup, and which default agent
- * to establish).
+ * Brand-neutral, so a product rename never moves it. Earlier CLIs stored the same
+ * setting under a key named after the product; those are still READ
+ * ({@link legacyAgentConfigKeys}), and every write replaces them with this one.
+ *
+ * The harness name the CLI sends when it asks for a default agent is not a
+ * constant here at all: it is `FIRST_PARTY_HARNESS.provider`. The server never
+ * takes the managed-session provider from the wire — `sessionInferenceRelay.js`
+ * fixes it itself, because it selects the relay capability and composes the
+ * `provider_model` budget key, none of which is a caller's choice — so the CLI
+ * names itself only where that legitimately matters (the trust-tier lookup, and
+ * which default agent to establish).
+ */
+exports.AGENT_CONFIG_KEY = 'firstPartyHarnessAgentId';
+/** `a-b` → `aB`: how a hyphenated spelling became part of a config key. */
+function camelCaseSlug(slug) {
+    return slug.replace(/-([a-z0-9])/g, (_, next) => next.toUpperCase());
+}
+// TODO(identity): move to auth-core — the identity module records legacy ENV
+// names; it has no notion of a legacy CONFIG key yet.
+/**
+ * Keys earlier CLIs stored the agent setting under: `<camelCased spelling>AgentId`
+ * for every spelling of the harness, canonical first.
+ *
+ * Derived rather than listed so no product name is written here — and so the key
+ * is read for exactly as long as its spelling is accepted anywhere else.
+ */
+function legacyAgentConfigKeys() {
+    return (0, auth_core_1.firstPartyHarnessSpellings)().map((spelling) => `${camelCaseSlug(spelling)}AgentId`);
+}
+/** Read the setting from a config record: the neutral key first, then each older key. */
+function readAgentSetting(config) {
+    for (const key of [exports.AGENT_CONFIG_KEY, ...legacyAgentConfigKeys()]) {
+        const raw = config[key];
+        if (typeof raw === 'string' && raw.trim()) {
+            return { value: raw.trim(), key, legacy: key !== exports.AGENT_CONFIG_KEY };
+        }
+    }
+    return { value: undefined, key: undefined, legacy: false };
+}
+/**
+ * The setting as the effective config holds it. THROWS when the config file is
+ * unparseable, exactly as `loadConfig` does — callers that must not fail catch it.
  */
-exports.SKY_CODE_HARNESS = 'sky-code';
+function readConfiguredAgentSetting() {
+    return readAgentSetting((0, config_1.loadConfig)());
+}
+/**
+ * A copy of `raw` with the setting written under the neutral key (or removed when
+ * `id` is undefined) and EVERY older key removed — so a later read can never find a
+ * stale value under a name this write did not touch.
+ */
+function withAgentSetting(raw, id) {
+    const next = { ...raw };
+    for (const key of legacyAgentConfigKeys())
+        delete next[key];
+    if (id)
+        next[exports.AGENT_CONFIG_KEY] = id;
+    else
+        delete next[exports.AGENT_CONFIG_KEY];
+    return next;
+}
 /**
  * Mirrored from `@skrr-ai/inference-broker`, for the same reason
  * `harness-tiers.ts` mirrors the daemon's trust table: importing the package
  * would pull a loopback SERVER into `skrr code doctor` and into every unmanaged
  * `skrr code` startup, to read two string constants.
  *
- * `sky-code-managed.spec.ts` asserts these against the package, so a rename there
+ * `first-party-harness-managed.spec.ts` asserts these against the package, so a rename there
  * fails a test here rather than silently making the posture check blind.
  */
 exports.MANAGED_SESSION_ENV = 'OVERSKY_MANAGED_SESSION';
@@ -112,7 +161,7 @@ exports.BROKER_SOCKET_ENV = 'OVERSKY_INFERENCE_BROKER_SOCKET';
  * posture computed from the real `process.env` while claiming to describe the
  * supplied one is a diagnostic that lies.
  */
-function skyCodeServerUrl(env = process.env) {
+function configuredServerUrl(env = process.env) {
     const fromEnv = (env.OVERSKY_BASE_URL || env.OVERSKY_SERVER_URL || '').trim();
     if (fromEnv)
         return fromEnv;
@@ -137,7 +186,7 @@ function isHttpsUrl(value) {
 /**
  * The server URL as a diagnostic is allowed to say it: SCHEME AND HOST ONLY.
  *
- * `skyCodeServerUrl` returns `OVERSKY_BASE_URL` / `OVERSKY_SERVER_URL` /
+ * `configuredServerUrl` returns `OVERSKY_BASE_URL` / `OVERSKY_SERVER_URL` /
  * `loadConfig().baseURL` unmodified, and a URL may legally carry userinfo — so
  * `https://user:s3cret@host` put a password into `skrr code doctor --json`, which
  * `docs/cli/SKRR_CODE.md` calls safe to paste into a ticket and promises never
@@ -201,10 +250,18 @@ function managedSkipReason(env = process.env) {
             announce: false,
         };
     }
-    if (envFlagIsOff(env[exports.MANAGED_ENV_FLAG])) {
+    // The operator's opt-OUT (`FIRST_PARTY_HARNESS_ENV.managed`, neutral name first,
+    // older name second). Present because "run with my own key" has to be
+    // expressible without logging out, and because a test that asserts argv
+    // forwarding must be able to say "this run is not about acquisition" rather
+    // than depend on whether the machine happens to be signed in.
+    const managedFlag = (0, auth_core_1.readFirstPartyHarnessEnv)(env, 'managed');
+    if (envFlagIsOff(managedFlag.value)) {
         return {
             kind: 'disabled',
-            detail: `${exports.MANAGED_ENV_FLAG} is off`,
+            // The variable that was actually read — two names are honoured, and the one
+            // to change is the one that is set.
+            detail: `${managedFlag.name} is off`,
             announce: false,
         };
     }
@@ -218,7 +275,7 @@ function managedSkipReason(env = process.env) {
             announce: true,
         };
     }
-    const serverUrl = skyCodeServerUrl(env);
+    const serverUrl = configuredServerUrl(env);
     if (!isHttpsUrl(serverUrl)) {
         // The single most likely reason a developer sees BYOK when they expected
         // managed: `buildManagedInferenceRelayCredential` requires HTTPS, and
@@ -241,7 +298,7 @@ function managedSkipReason(env = process.env) {
  * or not this run ends up brokering. Both spellings are accepted, and the
  * space-separated form consumes its value token.
  *
- * Everything else is spliced out IN PLACE: `sky-code-passthrough.spec.ts` asserts
+ * Everything else is spliced out IN PLACE: `first-party-harness-passthrough.spec.ts` asserts
  * exact array equality, so order and adjacency are the contract, and a flag
  * separated from its value is a different command.
  */
@@ -336,7 +393,7 @@ function managedInferencePosture(env = process.env) {
             return {
                 status: 'warn',
                 detail: `${exports.MANAGED_SESSION_ENV}=1 but no ${exports.BROKER_SOCKET_ENV} is present — this process cannot reach a broker`,
-                remedy: 'Do not set the managed marker by hand; let `skrr code` or the daemon set it.',
+                remedy: `Do not set the managed marker by hand; let \`${auth_core_1.FIRST_PARTY_HARNESS.command}\` or the daemon set it.`,
             };
         }
         return {
@@ -352,7 +409,7 @@ function managedInferencePosture(env = process.env) {
         // than as a guess about what to print.
         return {
             status: 'ok',
-            detail: `would broker a managed session against ${serverOrigin(skyCodeServerUrl(env)) ?? 'the configured skrr server'}`,
+            detail: `would broker a managed session against ${serverOrigin(configuredServerUrl(env)) ?? 'the configured skrr server'}`,
         };
     }
     return {

package/dist/lib/{sky-code.d.ts → first-party-harness.d.ts}

@@ -1,38 +1,65 @@
 /**
- * WL-2.2 — locate and forward to the local `sky-code` engine.
+ * WL-2.2 — locate and forward to the local first-party harness engine.
  *
  * The same `gh → git` shape `exec-runtime-binary.ts` uses, for the same reason: the
- * Sky CLI is a REST client, the engine is a separately-built, separately-
+ * skrr CLI is a REST client, the engine is a separately-built, separately-
  * released binary with its own lifetime and failure model. Unifying them at
  * the command surface (`skrr code`) gives users one thing to type without
  * coupling the two release cycles.
  *
  * The naming constraint from the plan (§3) is load-bearing and easy to get
  * wrong: skrr already publishes `oversky` (daemon) and `skrr` (control
- * plane). This must NOT become a third top-level executable. `sky-code` is an
- * internal binary name; `skrr code` is the only public entry point.
+ * plane). This must NOT become a third top-level executable. The engine's file
+ * name (`firstPartyHarnessBinaryName()`) is internal; `skrr code` is the only
+ * public entry point.
+ *
+ * ── No product name in this file ──────────────────────────────────────────
+ *
+ * Every product-named value — the binary's file name, the engine home, the env
+ * var names, the display name — is read from the identity module in
+ * `@skrr-ai/auth-core` (`docs/architecture/skrr-code-identifier-rename-2026-09-13.md`).
+ * The engine's file name has more than one spelling while a rename is in
+ * flight, so resolution tries every spelling, canonical first, in each location.
+ */
+/**
+ * The error `execEngine` throws when no engine resolves. A value the commands
+ * compare against, so it is exported rather than retyped at each catch site.
  */
-/** Env override, mirroring the daemon's `OVERSKY_SKY_CODE_PATH`. */
-export declare const ENGINE_PATH_ENV = "OVERSKY_SKY_CODE_PATH";
+export declare const ENGINE_NOT_INSTALLED = "engine-not-installed";
 /**
- * The engine's user-state root. skrr Code's child of skrr's `~/.skrr/`.
+ * The engine's user-state root: the engine home under skrr's `~/.skrr/`.
  *
  * Honours `OVERSKY_CONFIG_DIR`, the same root override the daemon reads
  * (`daemon/src/bun-entry.ts`). Without it the CLI would keep looking under
  * `$HOME` for a user who relocated their skrr root, and would resolve a
  * different engine than the daemon — the exact divergence the managed-first
  * ordering below exists to prevent.
+ *
+ * The directory NAME follows the engine's own namespace, not the provider slug
+ * (`firstPartyHarnessHomeDirname`, contract §5): the engine reads its config and
+ * the managed `AGENTS.md` from here, so a home named after anything else would be
+ * a directory the engine never reads.
  */
 export declare function engineHome(env?: NodeJS.ProcessEnv): string;
-/** The user-level instruction root owned by skrr Code. */
-export declare function skyCodeInstructionHome(env?: NodeJS.ProcessEnv): string;
 /**
- * The managed install location — where the daemon, the Desktop app, and
- * `scripts/sky-code/build.mjs --install` all put the engine.
+ * The user-level instruction root the engine owns.
+ *
+ * Read under the neutral variable first and its older name second
+ * (`readFirstPartyHarnessEnv`). The older name is also the one the ENGINE reads,
+ * which is why {@link engineOwnedEnv} hands the resolved value to the engine under
+ * that name — otherwise the doctor would honour the neutral variable and the
+ * engine would not.
+ */
+export declare function engineInstructionHome(env?: NodeJS.ProcessEnv): string;
+/**
+ * The managed install location for one spelling of the binary (canonical by
+ * default) — where the daemon, the Desktop app, and
+ * `scripts/first-party-harness/build.mjs --install` all put the engine.
  */
-export declare function managedEnginePath(exeName: string, env?: NodeJS.ProcessEnv): string;
+export declare function managedEnginePath(env?: NodeJS.ProcessEnv, provider?: string): string;
 /**
- * The same managed location under the PREVIOUS config root.
+ * The same managed location under the PREVIOUS config root, for every spelling of
+ * the binary and every engine home name, canonical first.
  *
  * The root moved `~/.oversky` → `~/.skrr` in the skrr rename, and an engine
  * installed before that is still on disk under the old one. `daemon/src/
@@ -40,14 +67,28 @@ export declare function managedEnginePath(exeName: string, env?: NodeJS.ProcessE
  * the same machine the daemon found the engine and `skrr code` reported that no
  * engine was installed — the same product, the same 106 MB binary, two answers.
  *
- * Returns null when an explicit `OVERSKY_CONFIG_DIR` is set, matching the
- * daemon: that override names one root deliberately, and reaching past it to a
- * hard-coded home would defeat the pinning {@link engineHome} relies on.
+ * The engine-home move (`migrateFirstPartyHarnessHome`) only ever works under the
+ * CURRENT root, so nothing renames a binary here — which is why this list carries
+ * every spelling rather than only the canonical one.
+ *
+ * Empty when an explicit `OVERSKY_CONFIG_DIR` is set, matching the daemon: that
+ * override names one root deliberately, and reaching past it to a hard-coded home
+ * would defeat the pinning {@link engineHome} relies on.
  */
-export declare function legacyManagedEnginePath(exeName: string, env?: NodeJS.ProcessEnv): string | null;
+export declare function legacyManagedEnginePaths(env?: NodeJS.ProcessEnv): string[];
+/** The `bin` directories {@link legacyManagedEnginePaths} looks in. */
+export declare function legacyManagedEngineBinDirs(env?: NodeJS.ProcessEnv): string[];
 export interface EngineResolution {
     path: string | null;
     source: 'env' | 'path' | 'managed' | 'legacy-managed' | 'fallback' | 'unresolved';
+    /**
+     * The variable an explicit override was read from — set whenever one was set,
+     * including an override that was refused. The doctor names it, because an
+     * operator fixing a bad override needs to know WHICH of its names they set.
+     */
+    envName?: string;
+    /** True when {@link envName} is an older name for the override. */
+    legacyEnv?: boolean;
 }
 /**
  * Resolve the engine binary, reporting WHERE it came from.
@@ -56,19 +97,23 @@ export interface EngineResolution {
  * binary am I actually running" is the first question when a managed session
  * and an interactive session behave differently.
  *
- * `env` is checked first and is absolute-only. A relative `OVERSKY_SKY_CODE_PATH`
+ * The env override is checked first and is absolute-only. A relative override
  * would resolve against the caller's cwd, which for an agent-invoked command is
- * attacker-influenced: a repo containing `./sky-code` could hijack the engine.
+ * attacker-influenced: a repo containing a file named like the engine could
+ * hijack it. It is read under its neutral name first and its older name second.
  *
- * **Order: env → managed → PATH → well-known (WL-6.2).**
+ * **Order: env → managed → PATH → well-known (WL-6.2).** Within each location
+ * every spelling of the binary is tried, canonical first — the daemon's order —
+ * so an engine installed under an older name still resolves, and the canonical
+ * one wins wherever both exist.
  *
  * The managed location beating `PATH` is the load-bearing part, and it is a
  * deliberate reversal of the obvious ordering.
  *
  * WL-6.2's acceptance criterion is that "Desktop-bundled and standalone
  * installations resolve the same version deterministically". With `PATH` first
- * they do not: a Desktop app that ships a pinned, signed engine into
- * `~/.skrr/sky-code/bin` silently loses to whatever `sky-code` happens to sit
+ * they do not: a Desktop app that ships a pinned, signed engine into the managed
+ * `bin` directory silently loses to whatever engine binary happens to sit
  * earlier on the user's `PATH` — a months-old dev build, a Homebrew copy of a
  * different version, a shim from an uninstalled package manager. The user sees
  * one product and gets two engines depending on their shell, and the daemon
@@ -81,6 +126,9 @@ export interface EngineResolution {
  *
  * `skrr code doctor` prints the winning `source`, so a surprising resolution is
  * one command away from being explained rather than being a mystery.
+ *
+ * Pure: it reads the filesystem and moves nothing. The engine-home move runs in
+ * {@link execEngine}, before it resolves, so the doctor stays safe to run anywhere.
  */
 export declare function resolveEngine(env?: NodeJS.ProcessEnv): EngineResolution;
 /**
@@ -124,20 +172,20 @@ export declare const DEDICATED_RUNTIME_ENGINE_MESSAGE = "On a Dedicated Runtime,
  * Message shown when no engine is installed.
  *
  * Points at the DAEMON's managed installer rather than at a package manager.
- * The earlier version of this text offered `brew install
- * dush1023/oversky/sky-code` and `curl .../sky-code/install.sh | bash`; neither
- * exists — the tap carries only the `oversky` formula and the feed serves no
- * install script — so a user following it hit a 404 and a 403 and reasonably
- * concluded the engine was not real.
+ * The earlier version of this text offered a Homebrew formula for the engine and
+ * a `curl .../install.sh | bash` on the update feed; neither exists — the tap
+ * carries only the `oversky` formula and the feed serves no install script — so
+ * a user following it hit a 404 and a 403 and reasonably concluded the engine
+ * was not real.
  *
  * The managed path is also the only one that establishes provenance: it
  * verifies the signed manifest and writes the sidecar the daemon reads before
  * it will hand the engine a platform credential. A hand-placed binary works, and
  * since the owner decision of 2026-08-11 it runs at the SAME tier as a managed
- * one — the daemon's floor for `sky-code` is Tier 1 regardless of provenance
- * (OSK-3894; this said "stays at Tier 2"). The managed path is still the
- * recommendation, but the reason is now "you can prove which bytes ran" rather
- * than "otherwise you get a weaker credential".
+ * one — the daemon's floor for the first-party harness is Tier 1 regardless of
+ * provenance (OSK-3894; this said "stays at Tier 2"). The managed path is still
+ * the recommendation, but the reason is now "you can prove which bytes ran"
+ * rather than "otherwise you get a weaker credential".
  *
  * Keep this in step with what actually ships. An install instruction that does
  * not work is worse than none: it moves the failure from "I could not find how
@@ -253,7 +301,7 @@ export interface EngineSpawnOptions {
  *
  * Exported because two callers need ONE answer to "does this machine have a
  * provider key at all": this module, to decide what the engine inherits, and the
- * BYOK fallback line in `sky-code-broker.ts`, which used to promise "continuing
+ * BYOK fallback line in `first-party-harness-broker.ts`, which used to promise "continuing
  * with your own provider credentials" on a machine that had none (invariant I4 —
  * managed, BYOK and offline must never be confused). Two definitions of that
  * question is how the promise and the reality drift apart.
@@ -308,10 +356,33 @@ export declare function strippedProviderCredentialNames(env?: NodeJS.ProcessEnv)
  *
  * One sharp edge to know about before adding a subcommand: the shared sanitizer
  * strips anything ending in `_PASSWORD`, which includes the engine's own
- * `SKY_CODE_SERVER_PASSWORD` (Basic auth for `sky-code serve` / `web`). No
- * `skrr code` subcommand reaches those today — they are run against the engine
- * binary directly — so nothing regresses; a future `skrr code serve` would have to
- * pass that credential deliberately rather than rely on inheritance.
+ * server-password variable (`FIRST_PARTY_HARNESS_ENGINE.env.serverPassword`, Basic
+ * auth for the engine's `serve` / `web`). No `skrr code` subcommand reaches those
+ * today — they are run against the engine binary directly — so nothing regresses;
+ * a future `skrr code serve` would have to pass that credential deliberately,
+ * under that name, rather than rely on inheritance.
+ *
+ * The layering, in full: sanitized parent → the user's own model credential (BYOK
+ * only) → {@link engineOwnedEnv} → `extraEnv`.
  */
 export declare function engineSpawnEnv(env: NodeJS.ProcessEnv, extraEnv: Record<string, string>, mode: 'managed' | 'byok'): NodeJS.ProcessEnv;
+/**
+ * Settings the platform reads under NEUTRAL names, handed to the engine under the
+ * engine's OWN names.
+ *
+ * The engine is a fork with its own variable namespace
+ * (`FIRST_PARTY_HARNESS_ENGINE.env`), and it reads none of the platform's neutral
+ * names. So an operator who sets the neutral home override would see
+ * `skrr code doctor` honour it while the engine it launches ignored it — two
+ * answers to "where do my instructions live" from one command.
+ *
+ * Only when the value came from a name the engine does NOT read: a value set under
+ * the engine's own name is inherited already, and rewriting it would only replace
+ * the user's spelling of a path with ours. The resolved path is passed rather than
+ * the raw value, so the engine and the doctor agree on `~` expansion too.
+ *
+ * Not a credential and never one: it cannot reintroduce anything the sanitizer
+ * strips, and `extraEnv` still layers over it.
+ */
+export declare function engineOwnedEnv(env: NodeJS.ProcessEnv): Record<string, string>;
 export declare function execEngine(args: string[], env?: NodeJS.ProcessEnv, options?: EngineSpawnOptions): Promise<number>;