@skrr-ai/cli 0.1.78 → 0.1.80

package/dist/lib/daemonBroker.js

@@ -71,7 +71,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR = void 0;
+exports.HOSTED_MACHINE_CLI_HANDOFF_DESCRIPTOR = exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR = void 0;
 exports.normalizeBaseUrl = normalizeBaseUrl;
 exports.resolveBootstrapPath = resolveBootstrapPath;
 exports.resolveProfileBootstrapPaths = resolveProfileBootstrapPaths;
@@ -80,6 +80,7 @@ exports.resolveCliHandoffCandidatePaths = resolveCliHandoffCandidatePaths;
 exports.resolveExactProfileBootstrapPaths = resolveExactProfileBootstrapPaths;
 exports.findLiveDaemonBootstrap = findLiveDaemonBootstrap;
 exports.readBootstrap = readBootstrap;
+exports.inspectBootstrap = inspectBootstrap;
 exports.attemptDaemonBrokerLogin = attemptDaemonBrokerLogin;
 exports.isBrokeredHandoffToken = isBrokeredHandoffToken;
 exports.redeemBrokeredHandoffToken = redeemBrokeredHandoffToken;
@@ -95,9 +96,11 @@ const os = __importStar(require("node:os"));
 const auth_core_1 = require("@skrr-ai/auth-core");
 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 brokered_dpop_1 = require("./brokered-dpop");
 const auth_storage_1 = require("./auth-storage");
 const config_1 = require("./config");
 const cli_identity_1 = require("./cli-identity");
+const daemonRestartWait_1 = require("./daemonRestartWait");
 const REQUEST_TIMEOUT_MS = 20_000;
 /**
  * Normalize a base URL for equality comparison. Mirrors the daemon-side
@@ -230,6 +233,17 @@ function resolveBootstrapCandidatePaths(profile = 'default') {
  * user configures can point the broker somewhere else.
  */
 exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR = '/run/skrr-dedicated-runtime/cli-handoff/descriptor.json';
+/**
+ * A Hosted Machine's workload hand-off descriptor, published only on a box
+ * booted under the identity split (OSK-11981, OSK-12019), where the daemon runs
+ * as `oversky-daemon` and its island file is unreadable to the workload. Same
+ * format and same broker-only contract as the Dedicated descriptor
+ * (`daemon/src/dedicated-cli-handoff.ts`, `workloadCliHandoffTarget`), in a
+ * DIFFERENT directory so a Hosted Machine is never mistaken for a Dedicated
+ * Runtime guest (`runningOnDedicatedRuntimeGuest` keys on that directory). The
+ * parent is created by the box's launcher as root and owned by the daemon.
+ */
+exports.HOSTED_MACHINE_CLI_HANDOFF_DESCRIPTOR = '/run/skrr-hosted-machine/cli-handoff/descriptor.json';
 /** Where the cli-handoff broker looks, in order. */
 function resolveCliHandoffCandidatePaths(profile = 'default') {
     const candidates = resolveBootstrapCandidatePaths(profile);
@@ -237,7 +251,7 @@ function resolveCliHandoffCandidatePaths(profile = 'default') {
     // default profile regardless of `--profile`, so a narrower condition here would
     // only describe behaviour production never reaches.
     if (process.platform === 'linux') {
-        candidates.push(exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR);
+        candidates.push(exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR, exports.HOSTED_MACHINE_CLI_HANDOFF_DESCRIPTOR);
     }
     return candidates;
 }
@@ -286,21 +300,28 @@ function findLiveDaemonBootstrap({ profile = 'default', bootstrapPathOverride, }
  * file is malformed, the CLI shouldn't try to repair it).
  */
 function readBootstrap(filePath) {
+    const inspected = inspectBootstrap(filePath);
+    return inspected.state === 'ok' ? inspected.bootstrap : null;
+}
+function inspectBootstrap(filePath) {
     let raw;
     try {
         if (!fs.existsSync(filePath))
-            return null;
+            return { state: 'absent' };
         raw = fs.readFileSync(filePath, 'utf8');
     }
-    catch {
-        return null;
+    catch (err) {
+        // Removed between the exists check and the read: a daemon shutting down.
+        if (err.code === 'ENOENT')
+            return { state: 'absent' };
+        return { state: 'unreadable', detail: err.message };
     }
     let parsedJson;
     try {
         parsedJson = JSON.parse(raw);
     }
-    catch {
-        return null;
+    catch (err) {
+        return { state: 'invalid', detail: `not JSON: ${err.message}` };
     }
     // Shared wire parser (`@skrr-ai/auth-core/cli-handoff-wire`) validates the
     // fields a caller cannot proceed without — host, port, secret — and
@@ -309,13 +330,13 @@ function readBootstrap(filePath) {
     // port must be a real TCP port, and the secret is a fixed-width key.
     const parsed = (0, cli_handoff_wire_1.parseCliHandoffDescriptor)(parsedJson);
     if (!parsed)
-        return null;
+        return { state: 'invalid', detail: 'missing host, port or secret' };
     if (parsed.host !== '127.0.0.1' ||
         typeof parsed.port !== 'number' ||
         parsed.port > 65_535 ||
         typeof parsed.secret !== 'string' ||
         Buffer.from(parsed.secret, 'base64').length !== 32) {
-        return null;
+        return { state: 'invalid', detail: 'not a loopback descriptor with a 32-byte secret' };
     }
     // PID liveness — ESRCH means the daemon was force-killed and the file
     // outlived the process. EPERM means alive but not signalable by us,
@@ -327,11 +348,11 @@ function readBootstrap(filePath) {
         catch (err) {
             const code = err.code;
             if (code === 'ESRCH')
-                return null;
+                return { state: 'dead_pid', pid: parsed.pid, bootstrap: parsed };
             // EPERM / other: keep going.
         }
     }
-    return parsed;
+    return { state: 'ok', bootstrap: parsed };
 }
 /**
  * Try the daemon-as-broker handoff. Returns a tagged outcome so callers
@@ -343,12 +364,83 @@ function readBootstrap(filePath) {
  * PKCE", and `ok: true` means "we're done, persist + return".
  */
 async function attemptDaemonBrokerLogin(opts) {
+    const first = await attemptDaemonBrokerLoginOnce(opts);
+    if (first.ok || !isRestartShapedFailure(first))
+        return first;
+    // The local service may be restarting: a graceful restart removes the
+    // descriptor and republishes it only once the new daemon is listening
+    // (measured ~14s), and a crash leaves it naming a dead pid until launchd
+    // brings a replacement up. Every `skrr` process in that window used to be
+    // told "Not signed in" and succeed on an immediate retry (OSK-13222). Wait —
+    // bounded, and only when something says a daemon is coming back — and ask
+    // again.
     const profile = opts.profile ?? 'default';
-    const candidates = opts.candidatePathsOverride
+    const failedFingerprints = new Set();
+    if (first.descriptorPort !== undefined || first.descriptorPid !== undefined) {
+        failedFingerprints.add(`${first.descriptorPid ?? ''}:${first.descriptorPort ?? ''}`);
+    }
+    const waited = await (0, daemonRestartWait_1.awaitRestartedDaemon)({
+        profile,
+        ...(opts.restartWait ?? {}),
+        ready: () => {
+            const fresh = listUsableBootstraps(opts);
+            return fresh.some(({ bootstrap }) => !failedFingerprints.has(`${bootstrap.pid ?? ''}:${bootstrap.port}`));
+        },
+    });
+    if (!waited.waited)
+        return first;
+    const second = await attemptDaemonBrokerLoginOnce(opts);
+    if (second.ok)
+        return second;
+    return { ...second, restartWaitedMs: waited.waitedMs };
+}
+/**
+ * A failure that looks like the local daemon is absent or mid-restart rather
+ * than a daemon that answered: no usable descriptor, a refused port, or an
+ * uncoded 401 on a secret it rotates when it restarts.
+ */
+function isRestartShapedFailure(failure) {
+    if (failure.dedicatedGuest)
+        return false;
+    switch (failure.reason) {
+        case 'no_bootstrap':
+        case 'bootstrap_parse':
+        case 'network':
+            return true;
+        case 'stale_bootstrap':
+            return !failure.code;
+        default:
+            return false;
+    }
+}
+function candidatePathsFor(opts) {
+    const profile = opts.profile ?? 'default';
+    return opts.candidatePathsOverride
         ? [...opts.candidatePathsOverride]
         : opts.bootstrapPathOverride
             ? [opts.bootstrapPathOverride]
             : resolveCliHandoffCandidatePaths(profile);
+}
+/** Live descriptors whose serverUrl does not contradict this CLI's baseURL. */
+function listUsableBootstraps(opts) {
+    const out = [];
+    for (const candidate of candidatePathsFor(opts)) {
+        const bootstrap = readBootstrap(candidate);
+        if (!bootstrap)
+            continue;
+        if (typeof bootstrap.serverUrl === 'string' &&
+            bootstrap.serverUrl.length > 0 &&
+            typeof opts.baseURL === 'string' &&
+            opts.baseURL.length > 0 &&
+            normalizeBaseUrl(opts.baseURL) !== normalizeBaseUrl(bootstrap.serverUrl)) {
+            continue;
+        }
+        out.push({ bootstrap, sourcePath: candidate });
+    }
+    return out;
+}
+async function attemptDaemonBrokerLoginOnce(opts) {
+    const candidates = candidatePathsFor(opts);
     // Bound candidates (their serverUrl matches this CLI) in order, then unbound
     // ones. Every usable candidate is kept, not just the first: see below.
     // `sourcePath` rides along — the brokered-migration cleanup keys on whether
@@ -357,10 +449,18 @@ async function attemptDaemonBrokerLogin(opts) {
     const unbound = [];
     let mismatchedBootstrap = null;
     let mismatchedPath = null;
+    // The first descriptor that EXISTED but could not be used, so a failure can
+    // say what was on disk instead of "no daemon" (OSK-13222).
+    let unusableDescriptor = null;
     for (const candidate of candidates) {
-        const candidateBootstrap = readBootstrap(candidate);
-        if (!candidateBootstrap)
+        const inspection = inspectBootstrap(candidate);
+        if (inspection.state !== 'ok') {
+            if (inspection.state !== 'absent' && !unusableDescriptor) {
+                unusableDescriptor = { path: candidate, inspection };
+            }
             continue;
+        }
+        const candidateBootstrap = inspection.bootstrap;
         if (typeof candidateBootstrap.serverUrl === 'string' &&
             candidateBootstrap.serverUrl.length > 0 &&
             typeof opts.baseURL === 'string' &&
@@ -392,6 +492,25 @@ async function attemptDaemonBrokerLogin(opts) {
                 ...(mismatchedPath ? { descriptorPath: mismatchedPath } : {}),
             };
         }
+        if (unusableDescriptor) {
+            const { path: descriptorPath, inspection } = unusableDescriptor;
+            return {
+                ok: false,
+                reason: 'no_bootstrap',
+                detail: inspection.state === 'dead_pid'
+                    ? `The daemon hand-off ${descriptorPath} names pid ${inspection.pid}, which has exited`
+                    : `The daemon hand-off ${descriptorPath} could not be used: ${inspection.detail}`,
+                descriptorPath,
+                descriptorState: inspection.state,
+                ...(inspection.state === 'dead_pid'
+                    ? {
+                        descriptorPid: inspection.pid,
+                        descriptorPort: inspection.bootstrap.port,
+                        ...(inspection.bootstrap.daemonId ? { daemonId: inspection.bootstrap.daemonId } : {}),
+                    }
+                    : {}),
+            };
+        }
         return {
             ok: false,
             reason: 'no_bootstrap',
@@ -413,6 +532,8 @@ async function attemptDaemonBrokerLogin(opts) {
             outcome = {
                 ...outcome,
                 descriptorPath: outcome.descriptorPath ?? sourcePath,
+                descriptorPort: bootstrap.port,
+                ...(typeof bootstrap.pid === 'number' ? { descriptorPid: bootstrap.pid } : {}),
                 ...(bootstrap.daemonId ? { daemonId: bootstrap.daemonId } : {}),
                 ...(sourcePath === exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR
                     ? { dedicatedGuest: true }
@@ -432,18 +553,41 @@ async function brokerThrough(bootstrap, opts, sourcePath) {
     // either the caller prefers broker mode (auto-broker) or the durable mint is
     // not offered at all (the Dedicated guest shape — its hand-off-only secret
     // cannot mint a family, so the token route is the only door).
+    //
+    // The no-durable-mint policy for the AUTOMATIC path lives here, in the CLI,
+    // and not in the daemon (OSK-12018). On a laptop the daemon cannot tell an
+    // explicit `skrr login` from an agent-originated implicit sign-in — same
+    // uid, same island secret — so a daemon-side refusal of the legacy mint
+    // would either break explicit login or be bypassed by anyone who calls it
+    // the way login does. It is not a boundary, so it is not attempted. What the
+    // CLI CAN guarantee is that its own automatic path never mints and persists
+    // a refresh family: when `access_token` is advertised, a failed redeem is
+    // the answer, and the daemon's outage is reported with its repair.
+    //
+    // COMPATIBILITY WINDOW: a v1 descriptor (no `handoffModes`, so no
+    // `access_token`) still takes the durable mint on the automatic path below,
+    // because that is the only door an older daemon has and refusing it would
+    // sign every laptop user out on a CLI upgrade. Remove that fallback for the
+    // automatic path once no supported laptop daemon still writes a v1 island
+    // descriptor — the v2 island descriptor (`handoffModes` in
+    // `daemon/src/local-server.ts`) and its token route shipped together in
+    // 1a636216b0, so the condition is "every daemon in use is at or past that
+    // release", which is a fleet measurement, not a date.
     const modes = (0, cli_handoff_wire_1.advertisedHandoffModes)(bootstrap);
-    const offersAccessToken = modes.includes('access_token');
+    const offersAccessToken = (0, cli_handoff_wire_1.descriptorOffersAccessToken)(bootstrap);
     const offersRefreshFamily = modes.includes('refresh_family');
     const preferAccessToken = opts.preferHandoffMode === 'access_token';
     if (offersAccessToken && (preferAccessToken || !offersRefreshFamily)) {
         const redeem = await redeemCliHandoffToken(bootstrap, {
             forceRefresh: false,
             timeoutMs: opts.timeoutMs,
+            // OSK-12020 — ask for a key-bound token whenever the daemon can serve
+            // its proofs. Whether it IS bound is read from the answer's tokenType.
+            dpop: (0, cli_handoff_wire_1.descriptorOffersDpop)(bootstrap),
         });
         if (redeem.ok) {
             const response = redeem.body;
-            registerBrokeredHandoff(bootstrap, response.accessToken, sourcePath);
+            registerBrokeredHandoff(bootstrap, response.accessToken, sourcePath, response.tokenType === 'DPoP');
             if (sourcePath === exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR) {
                 // A guest descriptor's secret can ONLY redeem access tokens, so a
                 // stored cli-auth.json on this machine predates broker mode. Retire
@@ -467,20 +611,17 @@ async function brokerThrough(bootstrap, opts, sourcePath) {
                 ...(sourcePath ? { descriptorPath: sourcePath } : {}),
             };
         }
-        // The descriptor ALSO advertises the durable mint (a laptop island during
-        // transition): any redeem failure — refusal, network, outage — falls
-        // through to the legacy route below. When refresh_family is NOT offered,
-        // the redeem outcome is final: the legacy route would only answer
-        // 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;
+        // A redeem failure is final for the automatic path even when the
+        // descriptor ALSO offers the durable mint (the laptop island): falling
+        // through would silently mint and persist a refresh family nobody asked
+        // for, which is exactly what broker mode exists to stop (OSK-12018). The
+        // caller reports the outage (`describeBrokerRefusal`) and names
+        // `skrr login` as the way to a durable personal sign-in. When
+        // refresh_family is NOT offered (a guest) the legacy route would only
+        // answer 403 HANDOFF_BROKER_ONLY anyway. (An explicit `skrr login`
+        // against a laptop island never enters this branch: it prefers
+        // refresh_family, which is offered, and takes the mint below directly.)
+        return redeem;
     }
     return mintRefreshFamilyThrough(bootstrap, opts);
 }
@@ -508,7 +649,10 @@ async function redeemCliHandoffToken(bootstrap, opts = {}) {
             // No cliId — the family is daemon-owned; the caller is not enrolling a
             // device. forceRefresh bypasses the daemon's cached access token (the
             // 401-recovery path).
-            body: JSON.stringify({ forceRefresh: opts.forceRefresh === true }),
+            body: JSON.stringify({
+                forceRefresh: opts.forceRefresh === true,
+                ...(opts.dpop ? { dpop: true } : {}),
+            }),
             signal: controller.signal,
         });
     }
@@ -766,8 +910,24 @@ async function mintRefreshFamilyThrough(bootstrap, opts) {
  * and re-redeems on entry via `maybeAutoBroker`.
  */
 let _brokeredHandoff = null;
-function registerBrokeredHandoff(descriptor, accessToken, sourcePath) {
+function registerBrokeredHandoff(descriptor, accessToken, sourcePath, dpopBound = false) {
     _brokeredHandoff = { descriptor, accessToken, ...(sourcePath ? { sourcePath } : {}) };
+    // OSK-12020 — a token the daemon reported as `tokenType: 'DPoP'` carries
+    // `cnf.jkt`; every request it makes needs a fresh proof from the daemon's
+    // key (`brokered-dpop.ts`). Never inferred from having asked: an older
+    // server ignores the binding request and the daemon then says `Bearer`.
+    if (dpopBound) {
+        (0, brokered_dpop_1.registerDpopBinding)(accessToken, () => {
+            const current = (sourcePath ? readBootstrap(sourcePath) : null) ?? descriptor;
+            if (!current.host || !current.port || !current.secret) {
+                throw new Error('hand-off descriptor is missing its loopback address');
+            }
+            return { host: current.host, port: current.port, secret: current.secret };
+        });
+    }
+    else {
+        (0, brokered_dpop_1.clearDpopBinding)();
+    }
 }
 /**
  * True when `token` is the access token this process redeemed through the
@@ -790,15 +950,19 @@ async function redeemBrokeredHandoffToken(forceRefresh = true) {
     if (!state)
         return null;
     const descriptor = (state.sourcePath ? readBootstrap(state.sourcePath) : null) ?? state.descriptor;
-    const result = await redeemCliHandoffToken(descriptor, { forceRefresh });
+    const result = await redeemCliHandoffToken(descriptor, {
+        forceRefresh,
+        dpop: (0, cli_handoff_wire_1.descriptorOffersDpop)(descriptor),
+    });
     if (!result.ok)
         return null;
-    _brokeredHandoff = { ...state, descriptor, accessToken: result.body.accessToken };
+    registerBrokeredHandoff(descriptor, result.body.accessToken, state.sourcePath, result.body.tokenType === 'DPoP');
     return result.body;
 }
 /** @internal test seam — clears the module-scoped brokered credential. */
 function __resetBrokeredHandoffForTest() {
     _brokeredHandoff = null;
+    (0, brokered_dpop_1.clearDpopBinding)();
 }
 /**
  * True when a live local descriptor advertises broker-mode access — i.e.
@@ -908,7 +1072,7 @@ function shouldBrokerBeforeStoredCredential(descriptorPath = exports.DEDICATED_R
     if (!bootstrap)
         return false;
     const modes = (0, cli_handoff_wire_1.advertisedHandoffModes)(bootstrap);
-    if (!modes.includes('access_token') || modes.includes('refresh_family'))
+    if (!(0, cli_handoff_wire_1.descriptorOffersAccessToken)(bootstrap) || modes.includes('refresh_family'))
         return false;
     return retirableCliAuthFamily(bootstrap.serverUrl) !== null;
 }
@@ -1052,7 +1216,10 @@ const AUTH_SELF_MANAGED_COMMANDS = new Set([
  *     'access_token'`. On a descriptor that advertises broker mode the
  *     outcome is `brokered` — an in-memory access token, nothing written;
  *     the caller holds it for this process and the next `skrr` re-redeems.
- *     On a legacy/v1 descriptor the durable mint is persisted to the
+ *     A failed redeem on such a descriptor is returned as the outcome and
+ *     never retried as a durable mint (OSK-12018). Only on a legacy/v1
+ *     descriptor (no `access_token` advertised — the compatibility window
+ *     documented in `brokerThrough`) is the durable mint persisted to the
  *     keychain / cli-auth.json exactly as before.
  *   - May generate a new `cliId` if the config doesn't have one. The
  *     caller MUST persist `updatedConfig` so the next invocation

package/dist/lib/daemonBrokerRefusal.d.ts

@@ -32,6 +32,12 @@ export interface BrokerRefusalDescription {
     transient: boolean;
     /** True when the refusing daemon is a Dedicated Runtime guest's. */
     dedicatedGuest: boolean;
+    /**
+     * True when no daemon answered because the local service is down or
+     * restarting (OSK-13222). The person is not signed out — their sign-in
+     * lives in that service — so the message must not open with "Not signed in".
+     */
+    daemonUnavailable?: boolean;
     /** Machine-readable twin for `--json` error details. */
     broker: {
         reason: DaemonBrokerFailure['reason'];
@@ -41,6 +47,10 @@ export interface BrokerRefusalDescription {
         detail?: string;
         descriptorPath?: string;
         daemonId?: string;
+        descriptorState?: DaemonBrokerFailure['descriptorState'];
+        descriptorPid?: number;
+        descriptorPort?: number;
+        restartWaitedMs?: number;
     };
 }
 /**
@@ -70,3 +80,19 @@ export declare function describeGuestDaemonUnavailable(failure: DaemonBrokerFail
     onGuest: boolean;
     descriptorPresent?: boolean;
 }): BrokerRefusalDescription | null;
+/**
+ * What to tell a person on their own computer when NO daemon answered the
+ * hand-off, but something on disk says one was there (OSK-13222).
+ *
+ * The laptop twin of `describeGuestDaemonUnavailable`. A daemon that crashed
+ * leaves its descriptor naming a dead pid; one mid-restart has a descriptor
+ * whose port refuses, or a secret it already rotated; or the CLI waited for a
+ * restart that did not finish. Each of these used to read "Not signed in. Run
+ * `skrr login` first." — a claim about the person's account made on evidence
+ * about a local process. Their sign-in is held by that service; say the
+ * service is down and name what was read.
+ *
+ * Returns null when there is no evidence of a daemon at all (no descriptor,
+ * nothing waited for): "Not signed in" is then the true sentence.
+ */
+export declare function describeLocalDaemonUnavailable(failure: DaemonBrokerFailure, bin?: string): BrokerRefusalDescription | null;

package/dist/lib/daemonBrokerRefusal.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isAnsweredBrokerRefusal = isAnsweredBrokerRefusal;
 exports.describeBrokerRefusal = describeBrokerRefusal;
 exports.describeGuestDaemonUnavailable = describeGuestDaemonUnavailable;
+exports.describeLocalDaemonUnavailable = describeLocalDaemonUnavailable;
 /**
  * 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
@@ -97,18 +98,18 @@ function describeBrokerRefusal(failure, bin = 'skrr') {
     }
     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.`;
+            `The background service is signed in with a CI token, which cannot sign a person in. Use \`${bin} login\` ` +
+                `(\`--device-code\` without a terminal). A \`${bin} create-token\` token would not help: ${bin} commands reject it.`;
     }
     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.`;
+                `and \`${bin} login\` gives this CLI a durable sign-in of its own, without the service.`;
     }
     else {
         remedy =
             `\`${bin} daemon status\` and \`${bin} daemon logs\` show the service's side. ` +
-                `\`${bin} login\` signs this CLI in without it.`;
+                `\`${bin} login\` gives this CLI a durable sign-in of its own, without the service.`;
     }
     return {
         headline: refusal,
@@ -210,3 +211,81 @@ function describeGuestDaemonUnavailable(failure, opts) {
         },
     };
 }
+/**
+ * What to tell a person on their own computer when NO daemon answered the
+ * hand-off, but something on disk says one was there (OSK-13222).
+ *
+ * The laptop twin of `describeGuestDaemonUnavailable`. A daemon that crashed
+ * leaves its descriptor naming a dead pid; one mid-restart has a descriptor
+ * whose port refuses, or a secret it already rotated; or the CLI waited for a
+ * restart that did not finish. Each of these used to read "Not signed in. Run
+ * `skrr login` first." — a claim about the person's account made on evidence
+ * about a local process. Their sign-in is held by that service; say the
+ * service is down and name what was read.
+ *
+ * Returns null when there is no evidence of a daemon at all (no descriptor,
+ * nothing waited for): "Not signed in" is then the true sentence.
+ */
+function describeLocalDaemonUnavailable(failure, bin = 'skrr') {
+    if (failure.dedicatedGuest)
+        return null;
+    if (isAnsweredBrokerRefusal(failure))
+        return null;
+    const who = `The skrr background service on this computer${failure.daemonId ? ` (daemon ${failure.daemonId})` : ''}`;
+    const where = failure.descriptorPath ? ` (${failure.descriptorPath})` : '';
+    const waited = typeof failure.restartWaitedMs === 'number' && failure.restartWaitedMs > 0
+        ? ` Waited ${Math.max(1, Math.round(failure.restartWaitedMs / 1000))}s for it to restart.`
+        : '';
+    let headline = null;
+    if (failure.reason === 'network' && failure.descriptorPath) {
+        headline =
+            `${who} is not answering: its sign-in hand-off${where} names port ` +
+                `${failure.descriptorPort ?? '?'} on 127.0.0.1, where nothing is listening.`;
+    }
+    else if (failure.reason === 'stale_bootstrap') {
+        headline = `${who} refused this CLI's hand-off secret${where}, which it rotates when it restarts.`;
+    }
+    else if (failure.reason === 'bootstrap_parse' ||
+        failure.descriptorState === 'unreadable' ||
+        failure.descriptorState === 'invalid') {
+        headline = `${who} is not available: its sign-in hand-off${where} could not be read${failure.detail ? ` (${failure.detail.replace(/[.]$/, '')})` : ''}.`;
+    }
+    else if (failure.descriptorState === 'dead_pid') {
+        headline =
+            `${who} is not running: its sign-in hand-off${where} names pid ` +
+                `${failure.descriptorPid ?? '?'}, which has exited (a crash, or a restart in progress).`;
+    }
+    else if (failure.reason === 'no_bootstrap' && waited) {
+        headline = `${who} was restarting and did not publish its sign-in hand-off in time.`;
+    }
+    if (!headline)
+        return null;
+    const remedy = 'You are not signed out: your sign-in is held by that service, which normally restarts on its own. ' +
+        `Retry in a moment. \`${bin} daemon status\` and \`${bin} daemon logs\` show the service's side, ` +
+        `and \`${bin} login\` signs this CLI in without it.`;
+    return {
+        headline: `${headline}${waited}`,
+        remedy,
+        transient: true,
+        dedicatedGuest: false,
+        daemonUnavailable: true,
+        broker: {
+            reason: failure.reason,
+            ...(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 } : {}),
+            ...(failure.descriptorState ? { descriptorState: failure.descriptorState } : {}),
+            ...(typeof failure.descriptorPid === 'number'
+                ? { descriptorPid: failure.descriptorPid }
+                : {}),
+            ...(typeof failure.descriptorPort === 'number'
+                ? { descriptorPort: failure.descriptorPort }
+                : {}),
+            ...(typeof failure.restartWaitedMs === 'number'
+                ? { restartWaitedMs: failure.restartWaitedMs }
+                : {}),
+        },
+    };
+}

package/dist/lib/daemonRestartWait.d.ts

@@ -0,0 +1,39 @@
+export type DaemonRestartSignal = 'starting' | 'supervised' | 'none';
+/** A lock acquired within this window belongs to a daemon still starting up. */
+export declare const STARTING_WINDOW_MS = 60000;
+/** Total wait once a starting daemon is seen. Startup was measured at ~14s. */
+export declare const DEFAULT_RESTART_WAIT_MS = 20000;
+/** Wait for a supervisor to start a daemon when none holds the lock yet. */
+export declare const SUPERVISED_GRACE_MS = 4000;
+export declare const DEFAULT_POLL_MS = 250;
+/**
+ * Read the restart signal for `profile` from the daemon's own on-disk state.
+ * Never throws; anything unreadable reads as absent.
+ */
+export declare function probeDaemonRestart(profile: string, opts?: {
+    homeDir?: string;
+    now?: number;
+    platform?: NodeJS.Platform;
+}): DaemonRestartSignal;
+export interface AwaitRestartedDaemonOptions {
+    profile: string;
+    /** True once a fresh descriptor the caller has not already failed on exists. */
+    ready: () => boolean;
+    /** Total budget once a starting daemon is seen. `SKRR_DAEMON_RESTART_WAIT_MS` overrides; 0 disables. */
+    maxWaitMs?: number;
+    supervisedGraceMs?: number;
+    pollMs?: number;
+    probe?: (profile: string) => DaemonRestartSignal;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Told once when the wait begins. Defaults to one stderr line. */
+    notify?: (message: string) => void;
+}
+export interface AwaitRestartedDaemonResult {
+    /** True when a restart was plausible and the CLI waited for it. */
+    waited: boolean;
+    waitedMs: number;
+    /** True when a fresh descriptor appeared inside the budget. */
+    ready: boolean;
+}
+export declare function awaitRestartedDaemon(opts: AwaitRestartedDaemonOptions): Promise<AwaitRestartedDaemonResult>;