@skrr-ai/cli 0.1.51 → 0.1.52

package/dist/lib/cli-identity.js

@@ -0,0 +1,159 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.profileScopedCliId = profileScopedCliId;
+exports.hasStoredCredential = hasStoredCredential;
+exports.planLoginCliId = planLoginCliId;
+exports.cliIdForLogin = cliIdForLogin;
+exports.persistPresentedCliId = persistPresentedCliId;
+/**
+ * cli-identity.ts — which cliId a LOGIN presents, and when a profile gets its own.
+ *
+ * Reading the identity is `resolveCliId()` in `config.ts` (it has to live there:
+ * `auth-storage.ts` judges credential ownership by it, and this module reads
+ * auth-storage). This module owns the one decision a read must never make —
+ * issuing an identity — and the one write that restores a backed-up pair.
+ *
+ * Why a profile needs its own (OSK-12156): the server's `cli-handoff/confirm`
+ * retires every OTHER live cli family of (user, cliId) once a hand-off lands.
+ * That is right for one config replacing its own previous session, and wrong
+ * when every profile on the machine presents the same machine-scoped `cliId`:
+ * profile B's daemon-brokered login then revoked profile A's session, silently.
+ * The server scoping is already per cliId, so the fix is the id, not the route.
+ *
+ * Why only a profile with NO stored credential: an existing session was minted
+ * under the machine id, and the refresh route refuses a rotation that presents
+ * another. Re-identifying such a profile would log it out on its next refresh —
+ * and a re-login under a new id would leave its old family live (the confirm
+ * only sweeps the id it was minted for) in a bucket the server evicts
+ * oldest-first. So a profile keeps presenting the id its credential is bound
+ * to, and only a profile starting from nothing is issued one. That is also why
+ * an upgrade forces no re-login: nothing that already works changes id.
+ *
+ * The default profile keeps the machine id. It IS the machine file, and it is
+ * the identity every pre-profile install already presents.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = __importDefault(require("node:os"));
+const path = __importStar(require("node:path"));
+const auth_storage_1 = require("./auth-storage");
+const config_1 = require("./config");
+const cli_id_1 = require("./cli-id");
+const device_id_1 = require("./device-id");
+const keychain_1 = require("./keychain");
+/**
+ * A named profile's own identity. Deterministic in (host, user, config root,
+ * profile), so a profile that loses its config file and signs in again is
+ * issued the same id rather than scattering families, and two profiles — or the
+ * same profile name under two config roots — never share one. Same `cli_<12hex>`
+ * shape as the machine id: the server requires the `cli_` namespace.
+ */
+function profileScopedCliId(profile = (0, keychain_1.getActiveProfile)(), root = (0, config_1.configRoot)()) {
+    const hostname = node_os_1.default.hostname();
+    const username = node_os_1.default.userInfo().username || 'unknown';
+    const digest = (0, node_crypto_1.createHash)('sha256')
+        .update(`${hostname}|${username}|cli|profile:${profile}|root:${path.resolve(root)}`)
+        .digest('hex');
+    return `cli_${digest.slice(0, 12)}`;
+}
+/**
+ * Does this profile hold a credential it would present? Its own backend slot
+ * (ownership-checked, any origin) or a pre-migration token still in the config.
+ *
+ * A read that FAILS answers true: "keep the id you already present" is the
+ * outcome that cannot log anyone out, so doubt falls on that side.
+ */
+function hasStoredCredential(cfg) {
+    if (cfg.token || cfg.refreshToken)
+        return true;
+    try {
+        const read = (0, auth_storage_1.readFromBackend)();
+        return Boolean(read.bundle?.token || read.bundle?.refreshToken);
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Decide the id a login is about to present. Pure apart from the credential
+ * read; the caller persists `updatedConfig` (see `cliIdForLogin`).
+ */
+function planLoginCliId(cfg, deps = {}) {
+    const env = (0, cli_id_1.envCliIdOverride)();
+    if (env)
+        return { cliId: env, source: 'env' };
+    const issued = cfg.profileCliId?.trim();
+    if (issued)
+        return { cliId: issued, source: 'profile' };
+    if ((0, cli_id_1.isNamedProfile)() && !(deps.hasStoredCredential ?? hasStoredCredential)(cfg)) {
+        const cliId = profileScopedCliId();
+        return { cliId, source: 'issued', updatedConfig: { ...cfg, profileCliId: cliId } };
+    }
+    const machine = cfg.cliId?.trim();
+    if (machine)
+        return { cliId: machine, source: 'machine' };
+    const cliId = (0, device_id_1.generateCliId)();
+    return { cliId, source: 'machine', updatedConfig: { ...cfg, cliId } };
+}
+/**
+ * The id an interactive login presents, persisted BEFORE the exchange so a
+ * retry — or a sibling process — presents the same one.
+ */
+function cliIdForLogin(cfg = (0, config_1.loadConfig)()) {
+    const plan = planLoginCliId(cfg);
+    if (plan.updatedConfig)
+        (0, config_1.saveConfig)(plan.updatedConfig);
+    return plan.cliId;
+}
+/**
+ * Record that this profile now presents `cliId` — a restored (refresh token,
+ * cliId) pair. A named profile records it as its own identity; writing the
+ * machine field from a named profile would re-identify the default profile and
+ * every profile still on the machine id, whose next refresh would be refused.
+ */
+function persistPresentedCliId(cfg, cliId) {
+    if ((0, cli_id_1.isNamedProfile)()) {
+        const current = cfg.profileCliId?.trim() || cfg.cliId?.trim();
+        if (current === cliId)
+            return;
+        (0, config_1.saveConfig)({ ...cfg, profileCliId: cliId });
+        return;
+    }
+    if (cfg.cliId !== cliId)
+        (0, config_1.saveConfig)({ ...cfg, cliId });
+}

package/dist/lib/commitments.d.ts

@@ -486,6 +486,10 @@ export interface CommitmentNextTickProjection {
         diagnosisKind?: string;
         terminalDispositionCensus?: {
             workFailures?: number;
+            /** Failed runs the runtime never started (`classifyRunFailure` machine). */
+            machineFailures?: number;
+            /** Failed runs whose result was rejected (`classifyRunFailure` contract). */
+            contractFailures?: number;
             budgetRefusals?: number;
             terminal?: number;
         };

package/dist/lib/commitments.js

@@ -655,6 +655,8 @@ function describeEvidenceHealth(health, criteriaCount) {
 const STALLED_DIAGNOSES = {
     scheduler_stalled: 'its expected checks are no longer arriving',
     work_failing: 'every recent run reached the agent and failed while doing the work',
+    runtime_failing: 'recent runs never started — the runtime refused them',
+    result_rejected: 'every recent run reached the agent, but its result was rejected',
     observation_unreadable: 'the latest check could not read every configured source',
     execution_budget_exhausted: 'recent planned work was skipped — the execution budget is exhausted',
     no_advancement: 'no server-recorded advancement exists inside the declared window',
@@ -674,8 +676,17 @@ function describeStalledHealth(commitment) {
     const kind = typeof liveness.diagnosisKind === 'string' ? liveness.diagnosisKind : undefined;
     const clause = (kind && STALLED_DIAGNOSES[kind]) ||
         'this loop has stopped producing; the reconciler did not record which check failed';
+    // What refused and what to change, when the reconciler recorded them
+    // (OSK-12137). A machine failure has a specific fix; printing only the
+    // verdict would send the owner to read run history for it.
+    const code = typeof liveness.diagnosisCode === 'string' && liveness.diagnosisCode
+        ? ` (${liveness.diagnosisCode})`
+        : '';
     const since = typeof liveness.unhealthySinceAt === 'string' ? ` (since ${liveness.unhealthySinceAt})` : '';
-    return `${clause}${since}`;
+    const fix = typeof liveness.diagnosisFix === 'string' && liveness.diagnosisFix
+        ? ` — ${liveness.diagnosisFix}`
+        : '';
+    return `${clause}${code}${since}${fix}`;
 }
 /** Render an interval back as a compact human string. */
 function describeIntervalMs(ms) {

package/dist/lib/config.d.ts

@@ -29,6 +29,23 @@ export interface CliConfig {
      * different daemonId.
      */
     cliId?: string;
+    /**
+     * The CLI identity of ONE named profile (OSK-12156), stored in that profile's
+     * own file and never in the machine file.
+     *
+     * `cliId` above is machine-scoped, so every profile used to present it — and
+     * the server's `cli-handoff/confirm` retires every OTHER live family of
+     * (user, cliId), so one profile's daemon-brokered login silently ended
+     * another's session. This is issued ONLY to a named profile that holds no
+     * stored credential at the moment it signs in (`cli-identity.ts`), because
+     * an existing session was minted under the machine id and a refresh that
+     * presents another is refused: a profile that already has a session keeps
+     * presenting the id it was minted under, so an upgrade forces no re-login.
+     *
+     * Never read this field, or `cliId`, to decide what to PRESENT — call
+     * `resolveCliId()` (`cli-id.ts`), the one resolver every caller goes through.
+     */
+    profileCliId?: string;
     /**
      * OSK-3892 — the agent a locally-hosted `skrr code` session is attributed to.
      *

package/dist/lib/config.js

@@ -53,6 +53,7 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const keychain_1 = require("./keychain");
 const auth_core_1 = require("@skrr-ai/auth-core");
+const cli_id_1 = require("./cli-id");
 const publicEndpoints_generated_1 = require("./publicEndpoints.generated");
 // Both from config/public-endpoints.json, the one domain contract, rather than a
 // fourth hand-copied pair. The CLI previously knew only about dev — there was no
@@ -174,7 +175,8 @@ const ENV_VAR = {
     serverUrl: 'OVERSKY_SERVER_URL',
     token: 'OVERSKY_TOKEN',
     refreshToken: 'OVERSKY_REFRESH_TOKEN',
-    cliId: 'OVERSKY_CLI_ID',
+    // OVERSKY_CLI_ID / SKRR_CLI_ID: `envCliIdOverride` (cli-id.ts), which
+    // `resolveCliId` shares, so the overlay and the resolver cannot disagree.
 };
 /**
  * Read one overlay variable under either prefix.
@@ -215,8 +217,8 @@ function overlayEnv(cfg) {
     const rt = envOverlayValue('refreshToken');
     if (rt && rt.length > 0)
         out.refreshToken = rt;
-    const cid = envOverlayValue('cliId');
-    if (cid && cid.length > 0)
+    const cid = (0, cli_id_1.envCliIdOverride)();
+    if (cid)
         out.cliId = cid;
     return out;
 }
@@ -275,6 +277,16 @@ function newConfigDir() {
  * and rejects a rotation against a different one. Split it per profile and a
  * second profile does not degrade — it fails to stay logged in.
  *
+ * So `cliId` stays here, and a profile's OWN identity is a different key,
+ * `profileCliId`, which is profile-scoped (OSK-12156). Sharing the machine id
+ * meant the server's cli-handoff confirm — which retires the other families of
+ * (user, cliId) — could not tell two profiles of one user apart, so one
+ * profile's daemon-brokered login ended another's session. A named profile that
+ * signs in holding no credential is now issued its own id; a profile that
+ * already has a session keeps the machine id it was minted under, because a
+ * refresh presenting another is refused. `resolveCliId()` (`cli-id.ts`) is the
+ * one reader.
+ *
  * `credentials.store` is a machine posture (keychain / file / env-only), and
  * `migrated` is a breadcrumb about this machine's DISK LAYOUT. Neither is a
  * property of which deployment you are addressing.

package/dist/lib/daemonBroker.d.ts

@@ -122,7 +122,7 @@ export interface DaemonBrokeredOutcome {
  * fall through to PKCE; `ci_token_refused` is the one we surface
  * because re-driving it via PKCE would not change the outcome.
  */
-export type DaemonBrokerErrorReason = 'no_bootstrap' | 'stale_bootstrap' | 'bootstrap_parse' | 'base_url_mismatch' | 'daemon_not_authed' | 'ci_token_refused' | 'handoff_broker_only' | 'rate_limited' | 'server_error' | 'network' | 'timeout' | 'unknown';
+export type DaemonBrokerErrorReason = 'no_bootstrap' | 'stale_bootstrap' | 'bootstrap_parse' | 'base_url_mismatch' | 'daemon_not_authed' | 'ci_token_refused' | 'handoff_broker_only' | 'rate_limited' | 'upstream_refused' | 'server_error' | 'network' | 'timeout' | 'unknown';
 export interface DaemonBrokerFailure {
     ok: false;
     reason: DaemonBrokerErrorReason;
@@ -132,6 +132,16 @@ export interface DaemonBrokerFailure {
     status?: number;
     /** Server-supplied error code when present (e.g. 'CI_TOKEN_REFUSED'). */
     code?: string;
+    /**
+     * Who refused, when the daemon answered at all: `daemon` for a refusal the
+     * local service made itself (not signed in, broker-only, its own outage),
+     * `server` for the skrr server's refusal of the daemon's request, carried
+     * through the loopback route (`upstreamCode` on the token route, the
+     * verbatim body on the legacy one). The two have different repairs, and a
+     * caller that cannot tell them apart can only say "Not signed in"
+     * (OSK-12149).
+     */
+    refusedBy?: 'daemon' | 'server';
     /**
      * For `base_url_mismatch`: the daemon's serverUrl, so the caller can
      * surface a helpful hint like "run `skrr login --base-url <X>` to use
@@ -139,11 +149,23 @@ export interface DaemonBrokerFailure {
      */
     daemonServerUrl?: string;
     /**
-     * For `base_url_mismatch` found locally: the descriptor file that named
-     * `daemonServerUrl`, so a message can say what was read rather than assert
-     * where "the" daemon is logged in (OSK-12117).
+     * The descriptor file the outcome came from. For `base_url_mismatch` found
+     * locally it is the file that named `daemonServerUrl`, so a message can say
+     * what was read rather than assert where "the" daemon is logged in
+     * (OSK-12117). For a refusal it is the descriptor whose daemon answered —
+     * which is how a caller knows the answer came from a Dedicated Runtime
+     * guest's daemon (`DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR`), where nobody
+     * signs in and the repair is the machine, not a login.
      */
     descriptorPath?: string;
+    /** The answering daemon's id, from its descriptor, when it published one. */
+    daemonId?: string;
+    /**
+     * True when the answering descriptor is a Dedicated Runtime guest's
+     * (`DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR`): nobody signs in there, so
+     * the repair for a refusal is the machine, never a login.
+     */
+    dedicatedGuest?: boolean;
 }
 export type DaemonBrokerOutcome = (DaemonBrokerResult & {
     ok: true;

package/dist/lib/daemonBroker.js

@@ -96,7 +96,7 @@ const loopback_http_1 = require("@skrr-ai/auth-core/loopback-http");
 const cli_handoff_wire_1 = require("@skrr-ai/auth-core/cli-handoff-wire");
 const auth_storage_1 = require("./auth-storage");
 const config_1 = require("./config");
-const device_id_1 = require("./device-id");
+const cli_identity_1 = require("./cli-identity");
 const REQUEST_TIMEOUT_MS = 20_000;
 /**
  * Normalize a base URL for equality comparison. Mirrors the daemon-side
@@ -120,6 +120,19 @@ function normalizeBaseUrl(u) {
         return (0, config_1.canonicalizeKnownBaseURL)(trimmed.toLowerCase());
     }
 }
+/**
+ * Codes the daemon's legacy `/v1/auth/cli-handoff` route writes itself. Every
+ * other coded body on that route is the server's, passed through verbatim.
+ */
+const DAEMON_OWN_HANDOFF_CODES = new Set([
+    cli_handoff_wire_1.CLI_HANDOFF_ERROR_BROKER_ONLY,
+    'BODY_TOO_LARGE',
+    'BODY_PARSE_FAILED',
+    'CLI_ID_INVALID',
+    'BASE_URL_MISMATCH',
+    'DAEMON_NOT_AUTHED',
+    'UPSTREAM_UNREACHABLE',
+]);
 /**
  * Compute the bootstrap file path. Exported for tests so they can assert
  * the platform fork without monkeypatching `os.platform()`.
@@ -394,6 +407,17 @@ async function attemptDaemonBrokerLogin(opts) {
     let outcome = null;
     for (const { bootstrap, sourcePath } of usable) {
         outcome = await brokerThrough(bootstrap, opts, sourcePath);
+        if (!outcome.ok) {
+            // Say which daemon answered: a guest's refusal has a different repair.
+            outcome = {
+                ...outcome,
+                descriptorPath: outcome.descriptorPath ?? sourcePath,
+                ...(bootstrap.daemonId ? { daemonId: bootstrap.daemonId } : {}),
+                ...(sourcePath === exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR
+                    ? { dedicatedGuest: true }
+                    : {}),
+            };
+        }
         if (outcome.ok || outcome.reason !== 'network')
             return outcome;
     }
@@ -448,6 +472,13 @@ async function brokerThrough(bootstrap, opts, sourcePath) {
         // 403 HANDOFF_BROKER_ONLY anyway.
         if (!offersRefreshFamily)
             return redeem;
+        const minted = await mintRefreshFamilyThrough(bootstrap, opts);
+        // Both doors refused: report the one that says more. The legacy route
+        // usually carries the server's code itself, but an older daemon's token
+        // route may be the only one that named it.
+        if (!minted.ok && !minted.code && redeem.code && redeem.reason !== 'network')
+            return redeem;
+        return minted;
     }
     return mintRefreshFamilyThrough(bootstrap, opts);
 }
@@ -517,6 +548,28 @@ async function redeemCliHandoffToken(bootstrap, opts = {}) {
                 ...(code ? { code } : {}),
             };
         }
+        // A daemon that names the SERVER's refusal of its own mint carries
+        // `upstreamCode` / `upstreamStatus` beside the 503 (older daemons omit them). Surface the
+        // server's code — `DEVICE_PROOF_PIN_MISMATCH` has a specific repair that
+        // `HANDOFF_TOKEN_UNAVAILABLE` cannot point at (OSK-12149).
+        const upstreamCode = typeof parsedBody?.upstreamCode === 'string'
+            ? parsedBody.upstreamCode
+            : undefined;
+        const upstreamStatus = typeof parsedBody?.upstreamStatus === 'number'
+            ? parsedBody.upstreamStatus
+            : undefined;
+        if (upstreamCode || upstreamStatus !== undefined) {
+            return {
+                ok: false,
+                reason: 'upstream_refused',
+                refusedBy: 'server',
+                detail: message,
+                ...(upstreamStatus !== undefined
+                    ? { status: upstreamStatus }
+                    : { status: response.status }),
+                ...(upstreamCode ? { code: upstreamCode } : code ? { code } : {}),
+            };
+        }
         return {
             ok: false,
             // 503 HANDOFF_TOKEN_UNAVAILABLE lands in server_error with its code
@@ -524,6 +577,7 @@ async function redeemCliHandoffToken(bootstrap, opts = {}) {
             // upstream unreachable, mint cool-down). That is a daemon outage, not a
             // decline, and the code keeps it diagnosable.
             reason: response.status >= 500 ? 'server_error' : 'unknown',
+            refusedBy: 'daemon',
             detail: message,
             status: response.status,
             ...(code ? { code } : {}),
@@ -610,7 +664,14 @@ async function mintRefreshFamilyThrough(bootstrap, opts) {
             };
         }
         if (response.status === 503 && code === 'DAEMON_NOT_AUTHED') {
-            return { ok: false, reason: 'daemon_not_authed', detail: message, status: 503, code };
+            return {
+                ok: false,
+                reason: 'daemon_not_authed',
+                refusedBy: 'daemon',
+                detail: message,
+                status: 503,
+                code,
+            };
         }
         // 429 is TRANSIENT and its remedy is time, which makes it the one failure
         // here that a fall-through cannot substitute for. Left in the `unknown`
@@ -644,12 +705,26 @@ async function mintRefreshFamilyThrough(bootstrap, opts) {
                 ...(daemonServerUrl ? { daemonServerUrl } : {}),
             };
         }
+        // A coded body the daemon did not write is the server's refusal of the
+        // daemon's mint, passed through verbatim (`cliHandoff.ts`). A 4xx one —
+        // observed: 401 DEVICE_PROOF_PIN_MISMATCH — is a decision with a named
+        // repair, and used to land in `unknown`, where no caller could classify it.
+        const refusedBy = code
+            ? DAEMON_OWN_HANDOFF_CODES.has(code)
+                ? 'daemon'
+                : 'server'
+            : undefined;
         return {
             ok: false,
-            reason: response.status >= 500 ? 'server_error' : 'unknown',
+            reason: response.status >= 500
+                ? 'server_error'
+                : refusedBy === 'server'
+                    ? 'upstream_refused'
+                    : 'unknown',
             detail: message,
             status: response.status,
             ...(code ? { code } : {}),
+            ...(refusedBy ? { refusedBy } : {}),
         };
     }
     // Happy path — validate the response shape minimally.
@@ -946,14 +1021,11 @@ async function maybeAutoBroker(opts) {
     if (opts.commandId && AUTH_SELF_MANAGED_COMMANDS.has(opts.commandId)) {
         return { triggered: false };
     }
-    // Mint a cliId on the fly when missing. Persisted by the caller on
+    // The same decision an interactive login makes (OSK-12156): a named profile
+    // with no stored credential is issued its own id, so a durable hand-off's
+    // confirm cannot retire another profile's session. Persisted by the caller on
     // success so the rotation row stays bound across processes.
-    let cliId = opts.cliConfig.cliId;
-    let updatedConfig;
-    if (!cliId) {
-        cliId = (0, device_id_1.generateCliId)();
-        updatedConfig = { ...opts.cliConfig, cliId };
-    }
+    const { cliId, updatedConfig } = (0, cli_identity_1.planLoginCliId)(opts.cliConfig);
     const outcome = await attemptDaemonBrokerLoginAndPersist({
         cliId,
         baseURL: opts.cliConfig.baseURL,

package/dist/lib/daemonBrokerRefusal.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What to tell a person whose local daemon ANSWERED the CLI hand-off and
+ * refused it (OSK-12149, OSK-12151).
+ *
+ * The auto-broker used to be "fail-quiet": every refusal except a rate limit
+ * and a base-URL mismatch was dropped, and the command then said only "Not
+ * signed in. Run `skrr login` first." That sentence is true and points at the
+ * wrong repair whenever the daemon's refusal is specific — observed: the server
+ * refused the daemon's own mint with `401 DEVICE_PROOF_PIN_MISMATCH`, which
+ * `skrr daemon login` repairs (an interactive daemon login re-pins its device
+ * key), and which on a Dedicated Runtime guest no login the tenant can run
+ * repairs at all.
+ *
+ * One function decides the headline and the remedy so the NOT_SIGNED_IN error,
+ * `skrr login`'s progress line and its headless refusal cannot drift apart.
+ */
+import type { DaemonBrokerFailure } from './daemonBroker';
+/**
+ * True when a daemon ANSWERED the hand-off and refused it — as opposed to no
+ * daemon being there to ask (`no_bootstrap`, a stale descriptor nobody listens
+ * behind). This is the case the CLI must explain rather than reduce to "Not
+ * signed in": the person has a daemon, it said something specific, and that
+ * decides whether `skrr login` would even help.
+ */
+export declare function isAnsweredBrokerRefusal(outcome: DaemonBrokerFailure): boolean;
+export interface BrokerRefusalDescription {
+    /** One sentence: who refused and what they said, with status and code. */
+    headline: string;
+    /** What to do about it — never a login the reader cannot perform. */
+    remedy: string;
+    /** True when waiting and retrying is the repair. */
+    transient: boolean;
+    /** True when the refusing daemon is a Dedicated Runtime guest's. */
+    dedicatedGuest: boolean;
+    /** Machine-readable twin for `--json` error details. */
+    broker: {
+        reason: DaemonBrokerFailure['reason'];
+        refusedBy?: 'daemon' | 'server';
+        status?: number;
+        code?: string;
+        detail?: string;
+        descriptorPath?: string;
+        daemonId?: string;
+    };
+}
+/**
+ * Describe a broker failure for a person, or null when there is nothing to
+ * say: no daemon was there to ask, or the failure already has its own message
+ * (`base_url_mismatch`, `rate_limited`).
+ */
+export declare function describeBrokerRefusal(failure: DaemonBrokerFailure, bin?: string): BrokerRefusalDescription | null;

package/dist/lib/daemonBrokerRefusal.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAnsweredBrokerRefusal = isAnsweredBrokerRefusal;
+exports.describeBrokerRefusal = describeBrokerRefusal;
+/**
+ * True when a daemon ANSWERED the hand-off and refused it — as opposed to no
+ * daemon being there to ask (`no_bootstrap`, a stale descriptor nobody listens
+ * behind). This is the case the CLI must explain rather than reduce to "Not
+ * signed in": the person has a daemon, it said something specific, and that
+ * decides whether `skrr login` would even help.
+ */
+function isAnsweredBrokerRefusal(outcome) {
+    switch (outcome.reason) {
+        case 'no_bootstrap':
+        case 'bootstrap_parse':
+        case 'network':
+            return false;
+        case 'stale_bootstrap':
+            // A bare 401 is the daemon refusing a descriptor secret that rotated;
+            // re-reading the file next time heals it. A coded one is a real answer.
+            return Boolean(outcome.code);
+        default:
+            return true;
+    }
+}
+/** Codes whose repair is signing the DAEMON in again (laptop only). */
+const DAEMON_RELOGIN_CODES = new Set([
+    'DEVICE_PROOF_PIN_MISMATCH',
+    'SESSION_REVOKED',
+    'PRINCIPAL_UNRESOLVED',
+    'DAEMON_NOT_AUTHED',
+]);
+/** Codes whose repair is time. */
+const TRANSIENT_CODES = new Set([
+    'DEVICE_PROOF_VERIFY_UNAVAILABLE',
+    'SERVICE_UNAVAILABLE',
+    'HANDOFF_RATE_LIMITED',
+    'RATE_LIMITED',
+    'UPSTREAM_UNREACHABLE',
+]);
+function statusAndCode(f) {
+    const parts = [typeof f.status === 'number' ? `HTTP ${f.status}` : '', f.code ?? ''].filter(Boolean);
+    return parts.length > 0 ? ` (${parts.join(' ')})` : '';
+}
+function sentence(detail) {
+    const d = (detail ?? '').trim();
+    if (!d)
+        return '';
+    return /[.!?]$/.test(d) ? ` ${d}` : ` ${d}.`;
+}
+/**
+ * Describe a broker failure for a person, or null when there is nothing to
+ * say: no daemon was there to ask, or the failure already has its own message
+ * (`base_url_mismatch`, `rate_limited`).
+ */
+function describeBrokerRefusal(failure, bin = 'skrr') {
+    if (!isAnsweredBrokerRefusal(failure))
+        return null;
+    if (failure.reason === 'base_url_mismatch' || failure.reason === 'rate_limited')
+        return null;
+    const dedicatedGuest = failure.dedicatedGuest === true;
+    const code = failure.code ?? '';
+    const who = dedicatedGuest
+        ? `This Dedicated Runtime's skrr service${failure.daemonId ? ` (daemon ${failure.daemonId})` : ''}`
+        : 'The skrr background service on this computer';
+    const refusal = failure.reason === 'timeout'
+        ? `${who} did not answer the sign-in hand-off in time.`
+        : failure.refusedBy === 'server' || failure.reason === 'upstream_refused'
+            ? `${who} asked the skrr server for a credential for this CLI, and the server refused${statusAndCode(failure)}.${sentence(failure.detail)}`
+            : `${who} could not hand this CLI a credential${statusAndCode(failure)}.${sentence(failure.detail)}`;
+    const transient = failure.reason === 'timeout' ||
+        TRANSIENT_CODES.has(code) ||
+        (failure.reason === 'server_error' && !DAEMON_RELOGIN_CODES.has(code));
+    let remedy;
+    if (dedicatedGuest) {
+        // Nobody signs in on a guest: the daemon's credential comes from the
+        // machine's attested bootstrap, and a tenant `skrr login` would only put a
+        // personal credential on a shared machine. Name the machine instead.
+        remedy = transient
+            ? 'This is usually temporary; retry in a minute. Nobody signs in on a Dedicated Runtime — ' +
+                `if it persists, check the machine from your own computer with \`${bin} machines dedicated health-check <lease-id>\` ` +
+                `(\`${bin} machines dedicated list\` shows the lease id).`
+            : 'Nobody signs in on a Dedicated Runtime: its daemon holds the account. From your own computer, run ' +
+                `\`${bin} machines dedicated health-check <lease-id>\` (\`${bin} machines dedicated list\` shows the lease id), ` +
+                `and \`${bin} machines dedicated restart <lease-id>\` if the hand-off stays refused.`;
+    }
+    else if (code === 'DEVICE_PROOF_PIN_MISMATCH') {
+        remedy =
+            `Run \`${bin} daemon login\` to sign the background service in again — an interactive daemon login re-pins its device key — then retry. ` +
+                `\`${bin} login\` signs this CLI in on its own instead.`;
+    }
+    else if (DAEMON_RELOGIN_CODES.has(code) || failure.reason === 'daemon_not_authed') {
+        remedy =
+            `Run \`${bin} daemon login\` to sign the background service in again, then retry. ` +
+                `\`${bin} login\` signs this CLI in on its own instead.`;
+    }
+    else if (failure.reason === 'ci_token_refused') {
+        remedy =
+            `The background service is signed in with a CI token, which cannot sign a person in. Use \`${bin} login\`, ` +
+                `or \`${bin} create-token\` for a CI credential.`;
+    }
+    else if (transient) {
+        remedy =
+            `This is usually temporary; retry in a minute. \`${bin} daemon status\` and \`${bin} daemon logs\` show the service's side, ` +
+                `and \`${bin} login\` signs this CLI in without it.`;
+    }
+    else {
+        remedy =
+            `\`${bin} daemon status\` and \`${bin} daemon logs\` show the service's side. ` +
+                `\`${bin} login\` signs this CLI in without it.`;
+    }
+    return {
+        headline: refusal,
+        remedy,
+        transient,
+        dedicatedGuest,
+        broker: {
+            reason: failure.reason,
+            ...(failure.refusedBy ? { refusedBy: failure.refusedBy } : {}),
+            ...(typeof failure.status === 'number' ? { status: failure.status } : {}),
+            ...(failure.code ? { code: failure.code } : {}),
+            ...(failure.detail ? { detail: failure.detail } : {}),
+            ...(failure.descriptorPath ? { descriptorPath: failure.descriptorPath } : {}),
+            ...(failure.daemonId ? { daemonId: failure.daemonId } : {}),
+        },
+    };
+}