@skrr-ai/cli 0.1.41 → 0.1.43

package/dist/lib/api-fetch.js

@@ -93,9 +93,14 @@ async function apiFetch(pathOrUrl, opts = {}) {
             ? assertTrustedAutonomousUrl(pathOrUrl, baseURL)
             : pathOrUrl
         : `${baseURL.replace(/\/+$/, '')}${pathOrUrl.startsWith('/') ? '' : '/'}${pathOrUrl}`;
+    // A FormData body passes through untouched — fetch sets the multipart
+    // boundary itself, and stringifying would destroy it. Upload commands
+    // (tasks attachments) need this on the session-scoped path, which is not
+    // in dataService.
+    const isFormData = typeof FormData !== 'undefined' && opts.body instanceof FormData;
     let body;
     if (opts.body !== undefined && method !== 'GET') {
-        body = JSON.stringify(opts.body);
+        body = isFormData ? opts.body : JSON.stringify(opts.body);
     }
     // Same rule as every `dataService` write (`@skrr-ai/data-provider`
     // idempotency), chosen once so the 401 retries below resend the same key.
@@ -145,7 +150,7 @@ async function apiFetch(pathOrUrl, opts = {}) {
             Accept: 'application/json',
             'X-Oversky-Origin': (0, refresh_1.getCliOrigin)(),
         };
-        if (opts.body !== undefined && method !== 'GET') {
+        if (opts.body !== undefined && method !== 'GET' && !isFormData) {
             headers['Content-Type'] = 'application/json';
         }
         if (credential.token) {

package/dist/lib/cli-installers.d.ts

@@ -25,12 +25,16 @@ export interface ManagedCliProviderState {
     source?: string;
     installable?: boolean;
     installDisabledReason?: string | null;
+    /**
+     * Whether the daemon can update this installed CLI in place, and why not.
+     * ABSENT from a daemon older than managed updates (OSK-10096) — read that as
+     * "this daemon cannot say", never as `false`.
+     */
+    updatable?: boolean;
+    updateDisabledReason?: string | null;
     platformSupported?: boolean;
     authentication?: ManagedCliAuthentication | null;
-    job?: {
-        id?: string;
-        status?: string;
-    } | null;
+    job?: ManagedCliInstallJob | null;
 }
 export interface CliInstallersResponse {
     daemonId?: string;
@@ -143,18 +147,34 @@ export declare function readinessForRows(rows: readonly ReadinessRow[], credenti
 }>;
 export interface ManagedCliInstallJob {
     id: string;
+    provider?: string;
+    displayName?: string;
     status: 'queued' | 'running' | 'succeeded' | 'failed';
+    /** `update` for an in-place update; absent from an older daemon, meaning install. */
+    kind?: 'install' | 'update';
+    startedAt?: string;
+    previousVersion?: string | null;
+    installedVersion?: string | null;
     error?: string;
     /**
      * The daemon's job log: the LAST lines only (a sliding window, 200 lines in
      * `daemon/src/cli-installers.ts`). This is the field the daemon sends.
      */
     logTail?: string[];
+    /**
+     * Lines the job has EVER logged (daemons with OSK-10179). With it, the lines
+     * new since the last poll are exactly the last `count − printed` of the tail,
+     * even when they repeat.
+     */
+    logLineCount?: number;
     /** Never sent by any daemon; kept so an older caller's shape still types. */
     log?: string[];
 }
 export interface StartInstallResponse {
     started?: boolean;
+    /** The daemon declined because the CLI is already there. */
+    alreadyInstalled?: boolean;
+    alreadyRunning?: boolean;
     provider?: ManagedCliProviderState;
     job?: {
         id?: string;
@@ -162,6 +182,35 @@ export interface StartInstallResponse {
     };
 }
 export declare function startManagedCliInstall(daemonId: string, provider: string, credential?: unknown): Promise<StartInstallResponse>;
+/**
+ * How long after a start request times out a job for the same provider is taken
+ * to be the one that request began.
+ *
+ * The relay holds the request while the daemon answers, and a gateway can cut
+ * that off at its own deadline: an update returned HTTP 504 after 21.9s while
+ * the job it started ran to success, and the caller was told the outcome was
+ * unknown (OSK-10096 verifier). A job that started within this window of the
+ * request is that request's job.
+ */
+export declare const START_TIMEOUT_JOB_WINDOW_MS = 120000;
+/** Ask the daemon to update an installed CLI in place (OSK-10096). */
+export declare function startManagedCliUpdate(daemonId: string, provider: string, credential?: unknown): Promise<StartInstallResponse>;
+/**
+ * How an update job ended, from the versions the daemon recorded on it:
+ * "Updated Claude Code 2.1.270 → 2.1.280." or "Claude Code is still 2.1.270:
+ * its updater found nothing newer." Null when the job does not carry both.
+ */
+/**
+ * The job a timed-out start request began, or null when none can be claimed.
+ *
+ * Read from the daemon's own inventory rather than assumed: it is the only
+ * party that knows whether the request reached it.
+ */
+export declare function jobStartedDespiteTimeout(daemonId: string, provider: string, credential?: unknown, opts?: {
+    now?: number;
+    windowMs?: number;
+}): Promise<ManagedCliInstallJob | null>;
+export declare function updateOutcomeLine(job: ManagedCliInstallJob): string | null;
 export declare function readManagedCliInstallJob(daemonId: string, jobId: string, credential?: unknown): Promise<{
     job?: ManagedCliInstallJob;
 }>;
@@ -174,6 +223,16 @@ export declare function readManagedCliInstallJob(daemonId: string, jobId: string
  * the end of what was already printed, and print only what follows it.
  */
 export declare function unseenLogLines(printed: readonly string[], tail: readonly string[]): string[];
+/**
+ * The new lines of a job's tail when the daemon reports its running line count:
+ * exactly the last `total − printedCount`, and how many of those already fell
+ * out of the window (the daemon keeps the last 200). Unlike overlap matching,
+ * this cannot mistake a repeated line for one already printed.
+ */
+export declare function newLogLinesByCount(printedCount: number, tail: readonly string[], total: number): {
+    lines: string[];
+    skipped: number;
+};
 /** A 100 MB download over a hotel connection is the case this has to survive. */
 export declare const INSTALL_MAX_WAIT_MS: number;
 export declare const INSTALL_POLL_INTERVAL_MS = 2000;

package/dist/lib/cli-installers.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INSTALL_POLL_INTERVAL_MS = exports.INSTALL_MAX_WAIT_MS = exports.ROW_READINESS_TIMEOUT_MS = exports.MANAGED_CLI_PROVIDER_SINCE = void 0;
+exports.INSTALL_POLL_INTERVAL_MS = exports.INSTALL_MAX_WAIT_MS = exports.START_TIMEOUT_JOB_WINDOW_MS = exports.ROW_READINESS_TIMEOUT_MS = exports.MANAGED_CLI_PROVIDER_SINCE = void 0;
 exports.describeProvidersNotOffered = describeProvidersNotOffered;
 exports.providersNotOffered = providersNotOffered;
 exports.listCliInstallers = listCliInstallers;
@@ -9,8 +9,12 @@ exports.readinessByProvider = readinessByProvider;
 exports.readinessKey = readinessKey;
 exports.readinessForRows = readinessForRows;
 exports.startManagedCliInstall = startManagedCliInstall;
+exports.startManagedCliUpdate = startManagedCliUpdate;
+exports.jobStartedDespiteTimeout = jobStartedDespiteTimeout;
+exports.updateOutcomeLine = updateOutcomeLine;
 exports.readManagedCliInstallJob = readManagedCliInstallJob;
 exports.unseenLogLines = unseenLogLines;
+exports.newLogLinesByCount = newLogLinesByCount;
 exports.followManagedCliInstallJob = followManagedCliInstallJob;
 /**
  * The daemon's managed-CLI installer inventory, as the CLI reads it.
@@ -85,12 +89,14 @@ function describeProvidersNotOffered(missing) {
         .join(', ');
 }
 function providersNotOffered(offered, known) {
-    // Canonicalize BOTH sides. An older daemon answers under the spelling it was
-    // built with — the 0.8.35 build reports the first-party harness under its
-    // older spelling, so a raw comparison against the current one reported it missing on
-    // a machine where it is installed and working. Caught by running this against
-    // the very daemon the finding was about: the first version of this helper
-    // said "Not offered: devin, <first-party harness>" when only `devin` was true.
+    // Canonicalize BOTH sides. A daemon answers under the spelling it was built
+    // with — during the rename window the 0.8.35 build reported the first-party
+    // harness under its older spelling, so a raw comparison against the current
+    // one reported it missing on a machine where it was installed and working (the
+    // first version of this helper said "Not offered: devin, <first-party
+    // harness>" when only `devin` was true). This is INGRESS, so it canonicalizes
+    // accepted spellings only: since contract a retired spelling is not the
+    // harness, and a daemon still answering under one predates the wire release.
     const seen = new Set((offered ?? []).map((provider) => canonical(provider.provider)).filter(Boolean));
     return known.filter((provider) => !seen.has(canonical(provider)));
 }
@@ -211,6 +217,62 @@ async function readinessForRows(rows, credential, opts = {}) {
 async function startManagedCliInstall(daemonId, provider, credential) {
     return (0, api_fetch_1.apiFetch)(`/api/daemons/${encodeURIComponent(daemonId)}/cli-installers/${encodeURIComponent(provider)}/install`, { method: 'POST', body: {}, credential: credential });
 }
+/**
+ * How long after a start request times out a job for the same provider is taken
+ * to be the one that request began.
+ *
+ * The relay holds the request while the daemon answers, and a gateway can cut
+ * that off at its own deadline: an update returned HTTP 504 after 21.9s while
+ * the job it started ran to success, and the caller was told the outcome was
+ * unknown (OSK-10096 verifier). A job that started within this window of the
+ * request is that request's job.
+ */
+exports.START_TIMEOUT_JOB_WINDOW_MS = 120_000;
+/** Ask the daemon to update an installed CLI in place (OSK-10096). */
+async function startManagedCliUpdate(daemonId, provider, credential) {
+    return (0, api_fetch_1.apiFetch)(`/api/daemons/${encodeURIComponent(daemonId)}/cli-installers/${encodeURIComponent(provider)}/update`, { method: 'POST', body: {}, credential: credential });
+}
+/**
+ * How an update job ended, from the versions the daemon recorded on it:
+ * "Updated Claude Code 2.1.270 → 2.1.280." or "Claude Code is still 2.1.270:
+ * its updater found nothing newer." Null when the job does not carry both.
+ */
+/**
+ * The job a timed-out start request began, or null when none can be claimed.
+ *
+ * Read from the daemon's own inventory rather than assumed: it is the only
+ * party that knows whether the request reached it.
+ */
+async function jobStartedDespiteTimeout(daemonId, provider, credential, opts = {}) {
+    let response;
+    try {
+        response = await listCliInstallers(daemonId, credential);
+    }
+    catch {
+        return null;
+    }
+    const row = (response.providers ?? []).find((entry) => canonical(entry.provider) === canonical(provider));
+    const job = row?.job;
+    if (!job?.id)
+        return null;
+    if (job.status === 'queued' || job.status === 'running')
+        return job;
+    const startedAt = job.startedAt ? Date.parse(job.startedAt) : NaN;
+    if (!Number.isFinite(startedAt))
+        return null;
+    const now = opts.now ?? Date.now();
+    return now - startedAt <= (opts.windowMs ?? exports.START_TIMEOUT_JOB_WINDOW_MS) ? job : null;
+}
+function updateOutcomeLine(job) {
+    const before = job.previousVersion;
+    const after = job.installedVersion;
+    if (!before || !after)
+        return null;
+    const name = job.displayName || job.provider || 'The CLI';
+    return before === after
+        ? `${name} is still ${after}: its updater found nothing newer.`
+        : `Updated ${name} ${before} → ${after}.`;
+}
 async function readManagedCliInstallJob(daemonId, jobId, credential) {
     return (0, api_fetch_1.apiFetch)(`/api/daemons/${encodeURIComponent(daemonId)}/cli-installers/jobs/${encodeURIComponent(jobId)}`, { credential: credential });
 }
@@ -237,6 +299,20 @@ function unseenLogLines(printed, tail) {
     }
     return [...tail];
 }
+/**
+ * The new lines of a job's tail when the daemon reports its running line count:
+ * exactly the last `total − printedCount`, and how many of those already fell
+ * out of the window (the daemon keeps the last 200). Unlike overlap matching,
+ * this cannot mistake a repeated line for one already printed.
+ */
+function newLogLinesByCount(printedCount, tail, total) {
+    const unseen = Math.max(0, total - printedCount);
+    if (unseen === 0)
+        return { lines: [], skipped: 0 };
+    if (unseen > tail.length)
+        return { lines: [...tail], skipped: unseen - tail.length };
+    return { lines: tail.slice(tail.length - unseen), skipped: 0 };
+}
 /** A 100 MB download over a hotel connection is the case this has to survive. */
 exports.INSTALL_MAX_WAIT_MS = 10 * 60_000;
 exports.INSTALL_POLL_INTERVAL_MS = 2_000;
@@ -256,6 +332,7 @@ exports.INSTALL_POLL_INTERVAL_MS = 2_000;
 async function followManagedCliInstallJob(input) {
     const deadline = Date.now() + (input.maxWaitMs ?? exports.INSTALL_MAX_WAIT_MS);
     let printed = [];
+    let printedCount = 0;
     for (;;) {
         const res = await readManagedCliInstallJob(input.daemonId, input.jobId, input.credential);
         const job = res.job;
@@ -264,7 +341,20 @@ async function followManagedCliInstallJob(input) {
         if (input.onLogLine) {
             // `logTail`, the field the daemon sends — this read `log`, which no daemon
             // has ever sent, so every install printed nothing until it ended (OSK-10103).
-            const fresh = unseenLogLines(printed, job.logTail ?? job.log ?? []);
+            const tail = job.logTail ?? job.log ?? [];
+            let fresh;
+            if (typeof job.logLineCount === 'number') {
+                // Exact: the daemon says how many lines exist in total (OSK-10179).
+                const { lines, skipped } = newLogLinesByCount(printedCount, tail, job.logLineCount);
+                if (skipped > 0) {
+                    input.onLogLine(`(… ${skipped} log line${skipped === 1 ? '' : 's'} not shown)`);
+                }
+                fresh = lines;
+                printedCount = Math.max(printedCount, job.logLineCount);
+            }
+            else {
+                fresh = unseenLogLines(printed, tail);
+            }
             for (const line of fresh)
                 input.onLogLine(line);
             printed = [...printed, ...fresh].slice(-MAX_TRACKED_LOG_LINES);

package/dist/lib/dedicated-machines.js

@@ -845,8 +845,10 @@ function selectDedicatedAttachHarness(lease, harnesses, engine) {
     }
     const providers = [...new Set(rows.map((row) => row.provider))];
     if (engine) {
-        // Any accepted spelling of an engine names it: a user who typed the first-party
-        // harness's older name means the row stored under its canonical one.
+        // Any ACCEPTED spelling of an engine names it — during a rename's alias window,
+        // a user who typed the first-party harness's older name means the row stored
+        // under its canonical one. A retired spelling is accepted nowhere, so it names
+        // no engine here either (`isSameHarnessProvider`).
         const match = rows.find((row) => (0, auth_core_1.isSameHarnessProvider)(row.provider, engine));
         if (!match) {
             return {

package/dist/lib/file-mime.js

@@ -68,7 +68,7 @@ const MIME_TYPES = {
     '.md': 'text/markdown',
     '.mjs': 'text/javascript',
     '.mkv': 'video/mkv',
-    '.mov': 'video/mov',
+    '.mov': 'video/quicktime',
     '.mp3': 'audio/mpeg',
     '.mp4': 'video/mp4',
     '.ogv': 'video/ogv',

package/dist/lib/first-party-harness-agent.js

@@ -220,7 +220,7 @@ async function resolveFirstPartyHarnessAgent(explicit, deps = {}, options = {})
         const created = options.createDefault === false
             ? null
             : await (deps.ensureDefaultAgent ?? ensureDefaultAgent)(
-            // Canonical: what the server stores. It accepts every spelling.
+            // Canonical: what the server stores, and the one spelling every server accepts.
             auth_core_1.FIRST_PARTY_HARNESS.provider, options.signal);
         if (created?.id) {
             return {
@@ -330,11 +330,12 @@ function readRawConfigKey() {
  * first real session read. Returns whether the file now holds it under the
  * neutral key.
  *
- * Reading alone used to leave it where it was, which is safe only while that key
- * is still an accepted spelling. The contract phase empties the identity's
- * aliases, `legacyAgentConfigKeys()` then stops naming the old key, and a user
+ * Reading alone used to leave it where it was. `legacyAgentConfigKeys()` keeps
+ * naming an old key after its spelling is retired (it reads the identity's
+ * ARTIFACT spellings, since the file predates the rename), but a key that is only
+ * ever read is one the next pruning of `formerSpellings` would strand, and a user
  * who never ran `--set`, `--clear` or logout would silently lose their setting.
- * Moving it here retires the old key long before that date.
+ * Moving it on the first session read retires the old key long before that.
  *
  * Only the session path calls this — `skrr code doctor` reports and never
  * writes. Best-effort: an unwritable config is left alone and still read.

package/dist/lib/first-party-harness-doctor.js

@@ -42,17 +42,6 @@ const first_party_harness_1 = require("./first-party-harness");
 const auth_core_1 = require("@skrr-ai/auth-core");
 const harness_tiers_1 = require("./harness-tiers");
 const first_party_harness_managed_1 = require("./first-party-harness-managed");
-/**
- * The variable one purpose was read from, and — when that was an older name — the
- * sentence that says so. `undefined` when the neutral name (or nothing) was used.
- */
-function legacyEnvNote(key, name) {
-    const neutral = auth_core_1.FIRST_PARTY_HARNESS_ENV[key].name;
-    if (!name || name === neutral)
-        return undefined;
-    return (`${name} is an older name for this setting and is still read; ` +
-        `rename it to ${neutral}, which wins when both are set.`);
-}
 /**
  * Project-level state dir — the ENGINE's own project marker
  * (`FIRST_PARTY_HARNESS_ENGINE.projectDirectory`). Basename deliberately differs
@@ -78,10 +67,12 @@ function projectStateDir(cwd) {
  * the answer one copy-paste away and keeps the property — and the promise is
  * reworded to match what is delivered rather than the other way round.
  *
- * The URL is the CANONICAL feed candidate. A manifest may also be published under
- * each older spelling (`firstPartyHarnessFeedCandidates`), and an installer that
- * finds nothing at the canonical URL tries those next — so the remedy names them
- * too. Without that, "the canonical URL 404s" would read as "there is no release"
+ * The URL is the CANONICAL feed candidate. While a rename's alias window is open
+ * a manifest may also be published under each alias (`firstPartyHarnessFeedCandidates`
+ * for a channel read), and an installer that finds nothing at the canonical URL
+ * tries those next — so the remedy names them too. A retired spelling is not
+ * among them: its channel pointers stopped moving when publishing stopped writing
+ * them, and naming one would point at a stale release. Without that, "the canonical URL 404s" would read as "there is no release"
  * on a feed an older pipeline published under the other spelling. The doctor
  * cannot say which candidate actually holds a release, because it does not probe;
  * it says where to look, in the order an installer looks.
@@ -97,15 +88,13 @@ function releaseChannelCheck(env) {
         manifestFilename: candidate.manifestFilename,
         channel,
     }));
-    const legacyNote = legacyEnvNote('channel', source);
     if (invalid) {
         return {
             name: 'release-channel',
             status: 'warn',
             detail: `${source}='${invalid}' is not a channel; following '${channel}' instead — ${canonical}`,
             remedy: `Set ${auth_core_1.FIRST_PARTY_HARNESS_ENV.channel.name} to one of ${auth_core_1.FIRST_PARTY_HARNESS_CHANNELS.join(', ')}, ` +
-                'or unset it to follow the default.' +
-                (legacyNote ? ` ${legacyNote}` : ''),
+                'or unset it to follow the default.',
         };
     }
     const alsoTried = alternates.filter((url) => url !== canonical);
@@ -114,10 +103,7 @@ function releaseChannelCheck(env) {
         status: 'ok',
         detail: `${channel} — ${canonical}`,
         remedy: 'Fetch that URL to see whether the channel has a published release, and which version.' +
-            (alsoTried.length
-                ? ` If it has none, an installer also tries ${alsoTried.join(', ')}.`
-                : '') +
-            (legacyNote ? ` ${legacyNote}` : ''),
+            (alsoTried.length ? ` If it has none, an installer also tries ${alsoTried.join(', ')}.` : ''),
     };
 }
 /**
@@ -159,7 +145,8 @@ function strandedLegacyEngine(env) {
 /**
  * Whether a managed engine resolved under an OLDER spelling of its file name.
  *
- * Not a fault: resolution tries every spelling on purpose, and the next
+ * Not a fault: resolution tries every artifact spelling on purpose (a former one
+ * included — the file predates the rename), and the next
  * `skrr code` run renames the file onto the canonical name (leaving a link at the
  * old one). Said anyway, because a path that does not match the name everything
  * else prints is exactly the surprise this module exists to explain.
@@ -196,14 +183,12 @@ function engineCheck(env) {
         };
     }
     if (bin && source === 'env') {
-        // Name the variable, not just "env": two names are read for this override,
-        // and the one to edit is the one that is set.
-        const legacyNote = resolution.legacyEnv ? legacyEnvNote('path', resolution.envName) : undefined;
+        // Name the variable, not just "env": an override is the one resolution the
+        // user set by hand, and the variable is what they would edit.
         return {
             name: 'engine',
             status: 'ok',
             detail: `${bin} (resolved via env ${resolution.envName})`,
-            ...(legacyNote ? { remedy: legacyNote } : {}),
         };
     }
     if (bin) {
@@ -232,7 +217,6 @@ function engineCheck(env) {
         };
     }
     const override = (0, auth_core_1.readFirstPartyHarnessEnv)(env, 'path');
-    const legacyNote = legacyEnvNote('path', override.name);
     if (override.value && !node_path_1.default.isAbsolute(override.value)) {
         return {
             name: 'engine',
@@ -241,7 +225,7 @@ function engineCheck(env) {
             // agent-invoked command the cwd is attacker-influenced, so a repo
             // containing a file named like the engine could otherwise hijack it.
             detail: `${override.name} is set to a relative path ('${override.value}') and was ignored`,
-            remedy: `Set ${pathVar} to an absolute path.${legacyNote ? ` ${legacyNote}` : ''}`,
+            remedy: `Set ${pathVar} to an absolute path.`,
         };
     }
     if (override.value) {
@@ -249,8 +233,7 @@ function engineCheck(env) {
             name: 'engine',
             status: 'fail',
             detail: `${override.name}='${override.value}' is not an executable file`,
-            remedy: `Point it at a real ${auth_core_1.FIRST_PARTY_HARNESS.displayName} engine build, or unset it to fall back to PATH.` +
-                (legacyNote ? ` ${legacyNote}` : ''),
+            remedy: `Point it at a real ${auth_core_1.FIRST_PARTY_HARNESS.displayName} engine build, or unset it to fall back to PATH.`,
         };
     }
     return {
@@ -451,7 +434,7 @@ function opencodeCheck(cwd) {
  * `daemon/src/harness-trust.ts` again.
  */
 function trustCheck() {
-    // The canonical slug. The shared table carries every spelling at the same tier,
+    // The canonical slug. The shared table carries every accepted spelling at the same tier,
     // so which one is asked does not change the answer — but the report prints the
     // name the platform stores.
     const harness = auth_core_1.FIRST_PARTY_HARNESS.provider;

package/dist/lib/first-party-harness-managed.d.ts

@@ -70,10 +70,15 @@ export declare const AGENT_FLAG_SPELLINGS: readonly ["--skrr-agent", "--oversky-
 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.
+ * for every ARTIFACT spelling of the harness, canonical first.
+ *
+ * A config file on a user's disk is an artifact: a CLI that last ran before a
+ * rename wrote the key under the product name it had then, and that file does not
+ * change when the spelling stops being accepted anywhere. So the key is derived
+ * from `firstPartyHarnessArtifactSpellings` — former spellings included — and is
+ * read (and moved onto the neutral key) for as long as the identity remembers the
+ * spelling, not merely for as long as some ingress still accepts it. Derived
+ * rather than listed, so no product name is written here.
  */
 export declare function legacyAgentConfigKeys(): string[];
 export interface AgentSetting {

package/dist/lib/first-party-harness-managed.js

@@ -90,17 +90,22 @@ exports.AGENT_CONFIG_KEY = 'firstPartyHarnessAgentId';
 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.
+// TODO(identity): move to auth-core — the identity module derives on-disk binary
+// names from its artifact spellings; 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.
+ * for every ARTIFACT 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.
+ * A config file on a user's disk is an artifact: a CLI that last ran before a
+ * rename wrote the key under the product name it had then, and that file does not
+ * change when the spelling stops being accepted anywhere. So the key is derived
+ * from `firstPartyHarnessArtifactSpellings` — former spellings included — and is
+ * read (and moved onto the neutral key) for as long as the identity remembers the
+ * spelling, not merely for as long as some ingress still accepts it. Derived
+ * rather than listed, so no product name is written here.
  */
 function legacyAgentConfigKeys() {
-    return (0, auth_core_1.firstPartyHarnessSpellings)().map((spelling) => `${camelCaseSlug(spelling)}AgentId`);
+    return (0, auth_core_1.firstPartyHarnessArtifactSpellings)().map((spelling) => `${camelCaseSlug(spelling)}AgentId`);
 }
 /** Read the setting from a config record: the neutral key first, then each older key. */
 function readAgentSetting(config) {
@@ -250,8 +255,7 @@ function managedSkipReason(env = process.env) {
             announce: false,
         };
     }
-    // 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
+    // The operator's opt-OUT (`FIRST_PARTY_HARNESS_ENV.managed`). 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.
@@ -259,8 +263,7 @@ function managedSkipReason(env = process.env) {
     if (envFlagIsOff(managedFlag.value)) {
         return {
             kind: 'disabled',
-            // The variable that was actually read — two names are honoured, and the one
-            // to change is the one that is set.
+            // The variable that was actually read, so the sentence names what to change.
             detail: `${managedFlag.name} is off`,
             announce: false,
         };

package/dist/lib/first-party-harness.d.ts

@@ -18,8 +18,10 @@
  * 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.
+ * An installed engine is an ARTIFACT: one installed before a rename is still on
+ * disk under its old file name after that name stops being accepted anywhere, so
+ * resolution tries every artifact spelling (`firstPartyHarnessArtifactSpellings`),
+ * canonical first, in each location. That recognises a file; it admits no input.
  */
 /**
  * The error `execEngine` throws when no engine resolves. A value the commands
@@ -44,11 +46,12 @@ export declare function engineHome(env?: NodeJS.ProcessEnv): string;
 /**
  * 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.
+ * Read under the platform's neutral variable first, then under the variable the
+ * ENGINE itself reads (`FIRST_PARTY_HARNESS_ENGINE.env.home`). The second is not a
+ * legacy fallback: it is the engine's own name, the engine honours it whatever the
+ * platform does, and a CLI that ignored it would report one instruction root while
+ * the engine it launches used another. {@link engineOwnedEnv} closes the other
+ * direction, handing a neutral-variable value to the engine under its own name.
  */
 export declare function engineInstructionHome(env?: NodeJS.ProcessEnv): string;
 /**
@@ -58,8 +61,9 @@ export declare function engineInstructionHome(env?: NodeJS.ProcessEnv): string;
  */
 export declare function managedEnginePath(env?: NodeJS.ProcessEnv, provider?: string): string;
 /**
- * The same managed location under the PREVIOUS config root, for every spelling of
- * the binary and every engine home name, canonical first.
+ * The same managed location under the PREVIOUS config root, for every artifact
+ * spelling of the binary (former spellings included) 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/
@@ -69,7 +73,7 @@ export declare function managedEnginePath(env?: NodeJS.ProcessEnv, provider?: st
  *
  * 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.
+ * every artifact 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
@@ -84,11 +88,9 @@ export interface EngineResolution {
     /**
      * 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.
+     * operator fixing a bad override needs to be told which variable to change.
      */
     envName?: string;
-    /** True when {@link envName} is an older name for the override. */
-    legacyEnv?: boolean;
 }
 /**
  * Resolve the engine binary, reporting WHERE it came from.
@@ -100,12 +102,12 @@ export interface EngineResolution {
  * 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 a file named like the engine could
- * hijack it. It is read under its neutral name first and its older name second.
+ * hijack it.
  *
  * **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.
+ * every artifact spelling of the binary is tried, canonical first — the daemon's
+ * order — so an engine installed under an older or former 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.
@@ -376,10 +378,12 @@ export declare function engineSpawnEnv(env: NodeJS.ProcessEnv, extraEnv: Record<
  * `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.
+ * Only when the neutral variable supplied the value: a value set only under the
+ * engine's own name is inherited already, and rewriting it would only replace the
+ * user's spelling of a path with ours. When both are set the neutral one wins, as
+ * it does in {@link engineInstructionHome}, so the engine is handed that one. 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.