@skrr-ai/cli 0.1.49 → 0.1.51

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/refreshClassification.js

@@ -16,6 +16,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TransientAuthFailure = exports.PermanentAuthFailure = void 0;
+exports.permanentReasonForRefreshCode = permanentReasonForRefreshCode;
 exports.classifyRefreshResponse = classifyRefreshResponse;
 const types_js_1 = require("./types.js");
 Object.defineProperty(exports, "PermanentAuthFailure", { enumerable: true, get: function () { return types_js_1.PermanentAuthFailure; } });
@@ -32,6 +33,33 @@ const PERMANENT_CODE_SET = new Set([
     'REFRESH_EXPIRED',
     'SESSION_REVOKED',
 ]);
+/**
+ * Server refusal codes that are permanent but are not themselves reason names.
+ *
+ * `DEVICE_PROOF_THUMBPRINT_MISMATCH` (`daemonRefreshTokens.verifyDeviceProofPinForRow`)
+ * means the proof was signed by a key other than the one enrolled on the daemon's
+ * row. Every retry is signed by the same key, so it can never succeed — but
+ * because it was not in the set above it fell through to the unknown-401 path,
+ * where a daemon retrying on a five-minute cadence never exhausted its budget:
+ * one laptop logged 741 "transient, retrying" refusals over four days, and the
+ * reason it eventually surfaced was `UNKNOWN_401` (OSK-12056).
+ */
+const PERMANENT_CODE_ALIASES = {
+    REFRESH_MISSING: 'REFRESH_INVALID',
+    DEVICE_PROOF_THUMBPRINT_MISMATCH: 'DEVICE_KEY_MISMATCH',
+};
+/**
+ * The permanent reason a 401 refresh refusal's `code` names, or `null` when the
+ * code is missing or unrecognised (an unknown-shape 401). The ONE mapping both
+ * this classifier and the daemon's `refresh.ts` read.
+ */
+function permanentReasonForRefreshCode(code) {
+    if (!code)
+        return null;
+    if (PERMANENT_CODE_SET.has(code))
+        return code;
+    return PERMANENT_CODE_ALIASES[code] ?? null;
+}
 /**
  * Classify an HTTP response from /api/auth/refresh (or /api/daemons/token/refresh)
  * into a discriminated union of success or failure.
@@ -64,17 +92,12 @@ function classifyRefreshResponse(status, body) {
     }
     // 401 — auth failure; check for known permanent code
     if (status === 401) {
-        if (body?.code === 'REFRESH_MISSING') {
-            return {
-                kind: 'failure',
-                failure: new types_js_1.PermanentAuthFailure('REFRESH_INVALID', body.message ?? 'Refresh token missing'),
-            };
-        }
-        const code = body?.code;
-        if (code && PERMANENT_CODE_SET.has(code)) {
+        const reason = permanentReasonForRefreshCode(body?.code);
+        if (reason) {
+            const fallback = body?.code === 'REFRESH_MISSING' ? 'Refresh token missing' : reason;
             return {
                 kind: 'failure',
-                failure: new types_js_1.PermanentAuthFailure(code, body?.message ?? code),
+                failure: new types_js_1.PermanentAuthFailure(reason, body?.message ?? fallback),
             };
         }
         // Unknown-shape 401 (no code, or a code we don't recognise). This is NOT a

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/sessionPermissionAuthority.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Session permission authority — the ONE rule that decides whether a session's
+ * execution contract governs the run's permissions, shared by the server and
+ * the daemon (OSK-11975 introduced it; it was implemented twice — the server
+ * read `kind !== 'commitment'`, the daemon read the `permissionSource` marker —
+ * which is exactly how a new contract kind or a new source value would drift
+ * them apart).
+ *
+ * The wire model:
+ *
+ *   - The contract is closed (`hasOnlyKeys` on the daemon), so "whose
+ *     permissions govern" can never ride INSIDE it. It is a top-level session
+ *     field: `permissionSource`.
+ *   - `'agent'` means the Agent's own configured permission mode, tool policy,
+ *     Grants, session env, MCP servers and machine consent govern the run,
+ *     exactly as for an unattended Task of the same Agent. Today only a
+ *     `commitment` contract may carry it.
+ *   - A `commitment` contract WITHOUT the marker (an older server mid-deploy)
+ *     still governs permissions — the marker is the version signal, so its
+ *     absence must keep the legacy fence, not silently lift it.
+ *   - `task_delivery` contracts always govern, marker or not.
+ *
+ * Server vs daemon asymmetry, on purpose: the server STAMPS the marker
+ * (`permissionSourceForContract`), so on its own side the predicate reduces to
+ * "a commitment never governs" — `contractGovernsPermissions(c,
+ * permissionSourceForContract(c))` is exactly `kind !== 'commitment'`. The
+ * daemon reads the marker it received, because it cannot distinguish "new
+ * server, agent permissions" from "old server, contract fence" any other way.
+ * Both call the same function; only the input differs.
+ */
+/** The wire vocabulary for `permissionSource`. Top-level session field. */
+export declare const SESSION_PERMISSION_SOURCES: readonly ["agent"];
+export type SessionPermissionSource = (typeof SESSION_PERMISSION_SOURCES)[number];
+/**
+ * The daemon capability that proves a build honours `permissionSource`. The
+ * server announces it in preflight and refuses to dispatch a Commitment Run to
+ * a daemon without it (`COMMITMENT_AGENT_PERMISSIONS_RUNTIME_UNSUPPORTED`), so
+ * the marker never reaches a daemon that would ignore it.
+ */
+export declare const COMMITMENT_AGENT_PERMISSIONS_CAPABILITY = "commitment_execution_contract_v2_agent_permissions";
+/**
+ * The minimal contract shape this rule reads. The predicate only ever needs
+ * `kind` — keeping the input structural means this module never imports the
+ * full `CommitmentExecutionContract` type, which lives daemon-side
+ * (`daemon/src/commitment-execution-contract.ts`) and server-side in the
+ * commitment services.
+ */
+export type PermissionContractKind = {
+    kind?: unknown;
+} | null | undefined;
+/**
+ * Untrusted wire input: anything but an exact vocabulary literal reads as
+ * absent. Never widen by coercion — an unrecognized future value must degrade
+ * to "contract governs", the conservative answer.
+ */
+export declare function normalizeSessionPermissionSource(value: unknown): SessionPermissionSource | undefined;
+/**
+ * What the server stamps on the wire for this contract. A `commitment`
+ * contract no longer carries permissions (OSK-11975); every other contract
+ * kind keeps its own authority and stamps nothing.
+ */
+export declare function permissionSourceForContract(contract: PermissionContractKind): SessionPermissionSource | undefined;
+/**
+ * Whether the contract is the run's PERMISSION authority — the single place
+ * this rule lives.
+ *
+ * True for a non-commitment contract regardless of marker, and for a
+ * commitment whose server did not declare agent permissions. False for no
+ * contract at all, and for a commitment carrying `permissionSource: 'agent'`,
+ * which then follows the Agent's own permissions exactly as a Task does while
+ * the contract keeps its non-permission roles (normalized shape, ephemeral
+ * worktree, result validation, `GIT_OPTIONAL_LOCKS`, provider restriction).
+ */
+export declare function contractGovernsPermissions(contract: PermissionContractKind, permissionSource: unknown): boolean;
+/**
+ * The contract when it governs permissions, else `undefined` — for the sites
+ * that used `executionContract` as "is this run permission-fenced".
+ */
+export declare function permissionGoverningContract<T extends {
+    kind?: unknown;
+}>(contract: T | null | undefined, permissionSource: unknown): T | undefined;

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/sessionPermissionAuthority.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Session permission authority — the ONE rule that decides whether a session's
+ * execution contract governs the run's permissions, shared by the server and
+ * the daemon (OSK-11975 introduced it; it was implemented twice — the server
+ * read `kind !== 'commitment'`, the daemon read the `permissionSource` marker —
+ * which is exactly how a new contract kind or a new source value would drift
+ * them apart).
+ *
+ * The wire model:
+ *
+ *   - The contract is closed (`hasOnlyKeys` on the daemon), so "whose
+ *     permissions govern" can never ride INSIDE it. It is a top-level session
+ *     field: `permissionSource`.
+ *   - `'agent'` means the Agent's own configured permission mode, tool policy,
+ *     Grants, session env, MCP servers and machine consent govern the run,
+ *     exactly as for an unattended Task of the same Agent. Today only a
+ *     `commitment` contract may carry it.
+ *   - A `commitment` contract WITHOUT the marker (an older server mid-deploy)
+ *     still governs permissions — the marker is the version signal, so its
+ *     absence must keep the legacy fence, not silently lift it.
+ *   - `task_delivery` contracts always govern, marker or not.
+ *
+ * Server vs daemon asymmetry, on purpose: the server STAMPS the marker
+ * (`permissionSourceForContract`), so on its own side the predicate reduces to
+ * "a commitment never governs" — `contractGovernsPermissions(c,
+ * permissionSourceForContract(c))` is exactly `kind !== 'commitment'`. The
+ * daemon reads the marker it received, because it cannot distinguish "new
+ * server, agent permissions" from "old server, contract fence" any other way.
+ * Both call the same function; only the input differs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMITMENT_AGENT_PERMISSIONS_CAPABILITY = exports.SESSION_PERMISSION_SOURCES = void 0;
+exports.normalizeSessionPermissionSource = normalizeSessionPermissionSource;
+exports.permissionSourceForContract = permissionSourceForContract;
+exports.contractGovernsPermissions = contractGovernsPermissions;
+exports.permissionGoverningContract = permissionGoverningContract;
+/** The wire vocabulary for `permissionSource`. Top-level session field. */
+exports.SESSION_PERMISSION_SOURCES = ['agent'];
+/**
+ * The daemon capability that proves a build honours `permissionSource`. The
+ * server announces it in preflight and refuses to dispatch a Commitment Run to
+ * a daemon without it (`COMMITMENT_AGENT_PERMISSIONS_RUNTIME_UNSUPPORTED`), so
+ * the marker never reaches a daemon that would ignore it.
+ */
+exports.COMMITMENT_AGENT_PERMISSIONS_CAPABILITY = 'commitment_execution_contract_v2_agent_permissions';
+/**
+ * Untrusted wire input: anything but an exact vocabulary literal reads as
+ * absent. Never widen by coercion — an unrecognized future value must degrade
+ * to "contract governs", the conservative answer.
+ */
+function normalizeSessionPermissionSource(value) {
+    return exports.SESSION_PERMISSION_SOURCES.includes(value)
+        ? value
+        : undefined;
+}
+/**
+ * What the server stamps on the wire for this contract. A `commitment`
+ * contract no longer carries permissions (OSK-11975); every other contract
+ * kind keeps its own authority and stamps nothing.
+ */
+function permissionSourceForContract(contract) {
+    return contract?.kind === 'commitment' ? 'agent' : undefined;
+}
+/**
+ * Whether the contract is the run's PERMISSION authority — the single place
+ * this rule lives.
+ *
+ * True for a non-commitment contract regardless of marker, and for a
+ * commitment whose server did not declare agent permissions. False for no
+ * contract at all, and for a commitment carrying `permissionSource: 'agent'`,
+ * which then follows the Agent's own permissions exactly as a Task does while
+ * the contract keeps its non-permission roles (normalized shape, ephemeral
+ * worktree, result validation, `GIT_OPTIONAL_LOCKS`, provider restriction).
+ */
+function contractGovernsPermissions(contract, permissionSource) {
+    if (!contract)
+        return false;
+    return !(contract.kind === 'commitment' && normalizeSessionPermissionSource(permissionSource) === 'agent');
+}
+/**
+ * The contract when it governs permissions, else `undefined` — for the sites
+ * that used `executionContract` as "is this run permission-fenced".
+ */
+function permissionGoverningContract(contract, permissionSource) {
+    return contract && contractGovernsPermissions(contract, permissionSource) ? contract : undefined;
+}

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/spawnEnv.d.ts

@@ -84,3 +84,25 @@ export declare const SENSITIVE_ENV_PREFIX_EXCEPTIONS: ReadonlySet<string>;
  * etc.) so legitimate tools keep working.
  */
 export declare function sanitizeSpawnEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * OSK-12134 — loopback names a spawned child must reach directly, never through
+ * a proxy. A harness talks to this machine constantly: the daemon's local
+ * bridges (browser, delegated CLI, message intents), the inference broker, and
+ * the engine's own loopback services (skrr Code's `session/new` reaches a local
+ * directory service and failed with "service failure" behind a shell proxy).
+ */
+export declare const LOOPBACK_NO_PROXY_HOSTS: readonly string[];
+/** True when `env` names a proxy some client in the child might honour. */
+export declare function envHasProxy(env: Readonly<Record<string, string | undefined>>): boolean;
+/**
+ * Return `env` with the loopback hosts appended to BOTH `NO_PROXY` and
+ * `no_proxy`, when (and only when) it names a proxy. Tools disagree on which
+ * spelling they read and whether they fall back to the other, so an unset
+ * spelling is seeded from the other one before the hosts are appended —
+ * seeding only the hosts would silently drop every existing exemption for a
+ * tool that prefers the unset spelling. Existing entries keep their order.
+ *
+ * Exported for a parent that layers a proxy onto the child's env AFTER
+ * {@link sanitizeSpawnEnv}: call it again on the final map.
+ */
+export declare function withLoopbackNoProxy<T extends Record<string, string | undefined>>(env: T): T;

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/spawnEnv.js

@@ -40,8 +40,10 @@
  * serve that case: a deny-list with a hole is not a deny-list.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SENSITIVE_ENV_PREFIX_EXCEPTIONS = exports.SENSITIVE_ENV_NAME_TOKENS = exports.SENSITIVE_ENV_SUFFIXES = exports.SENSITIVE_ENV_PREFIXES = exports.SENSITIVE_ENV_VARS = void 0;
+exports.LOOPBACK_NO_PROXY_HOSTS = exports.SENSITIVE_ENV_PREFIX_EXCEPTIONS = exports.SENSITIVE_ENV_NAME_TOKENS = exports.SENSITIVE_ENV_SUFFIXES = exports.SENSITIVE_ENV_PREFIXES = exports.SENSITIVE_ENV_VARS = void 0;
 exports.sanitizeSpawnEnv = sanitizeSpawnEnv;
+exports.envHasProxy = envHasProxy;
+exports.withLoopbackNoProxy = withLoopbackNoProxy;
 /**
  * Env vars that must NEVER reach a spawned subprocess.
  *
@@ -187,5 +189,62 @@ function sanitizeSpawnEnv(env) {
             continue;
         out[key] = value;
     }
-    return out;
+    return withLoopbackNoProxy(out);
+}
+/**
+ * OSK-12134 — loopback names a spawned child must reach directly, never through
+ * a proxy. A harness talks to this machine constantly: the daemon's local
+ * bridges (browser, delegated CLI, message intents), the inference broker, and
+ * the engine's own loopback services (skrr Code's `session/new` reaches a local
+ * directory service and failed with "service failure" behind a shell proxy).
+ */
+exports.LOOPBACK_NO_PROXY_HOSTS = ['127.0.0.1', 'localhost', '::1'];
+const PROXY_ENV_VARS = [
+    'HTTP_PROXY',
+    'http_proxy',
+    'HTTPS_PROXY',
+    'https_proxy',
+    'ALL_PROXY',
+    'all_proxy',
+];
+/** True when `env` names a proxy some client in the child might honour. */
+function envHasProxy(env) {
+    return PROXY_ENV_VARS.some((name) => typeof env[name] === 'string' && env[name].trim() !== '');
+}
+function appendNoProxyHosts(list, hosts) {
+    const entries = list
+        .split(',')
+        .map((entry) => entry.trim().toLowerCase())
+        .filter(Boolean);
+    // `*` already exempts everything, and some clients honour it only as the
+    // entire value, so appending to it would break them.
+    if (entries.includes('*'))
+        return list;
+    const missing = hosts.filter((host) => !entries.includes(host));
+    if (missing.length === 0)
+        return list;
+    const kept = list.replace(/[\s,]+$/, '');
+    return kept ? `${kept},${missing.join(',')}` : missing.join(',');
+}
+/**
+ * Return `env` with the loopback hosts appended to BOTH `NO_PROXY` and
+ * `no_proxy`, when (and only when) it names a proxy. Tools disagree on which
+ * spelling they read and whether they fall back to the other, so an unset
+ * spelling is seeded from the other one before the hosts are appended —
+ * seeding only the hosts would silently drop every existing exemption for a
+ * tool that prefers the unset spelling. Existing entries keep their order.
+ *
+ * Exported for a parent that layers a proxy onto the child's env AFTER
+ * {@link sanitizeSpawnEnv}: call it again on the final map.
+ */
+function withLoopbackNoProxy(env) {
+    if (!envHasProxy(env))
+        return env;
+    const upper = env.NO_PROXY?.trim() ? env.NO_PROXY : undefined;
+    const lower = env.no_proxy?.trim() ? env.no_proxy : undefined;
+    return {
+        ...env,
+        NO_PROXY: appendNoProxyHosts(upper ?? lower ?? '', exports.LOOPBACK_NO_PROXY_HOSTS),
+        no_proxy: appendNoProxyHosts(lower ?? upper ?? '', exports.LOOPBACK_NO_PROXY_HOSTS),
+    };
 }

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/types.d.ts

@@ -62,6 +62,11 @@ export interface TokenPair {
  *   - TOKEN_*         — access-token specific (server pushes 4402 close;
  *                       daemon classifies as TOKEN_INVALID/TOKEN_EXPIRED).
  *   - SESSION_REVOKED — admin/forensic revoke; whole family burned.
+ *   - DEVICE_KEY_MISMATCH — the refresh carried a device proof signed by a key
+ *                       other than the one enrolled on this daemon's row
+ *                       (server code `DEVICE_PROOF_THUMBPRINT_MISMATCH`).
+ *                       The daemon signs every retry with the same key, so
+ *                       retrying can never succeed.
  *   - UNKNOWN_401     — server returned 401 with a code we don't
  *                       recognize. Treated as permanent (better to prompt
  *                       re-auth than to loop forever) but tagged
@@ -74,7 +79,7 @@ export interface TokenPair {
  * Without this, the client `describeAuthFailure` exhaustiveness check
  * was silently broken for the non-REFRESH branches.
  */
-export type PermanentAuthReason = 'REFRESH_INVALID' | 'REFRESH_REUSED' | 'REFRESH_EXPIRED' | 'SESSION_REVOKED' | 'TOKEN_INVALID' | 'TOKEN_EXPIRED' | 'UNKNOWN_401';
+export type PermanentAuthReason = 'REFRESH_INVALID' | 'REFRESH_REUSED' | 'REFRESH_EXPIRED' | 'SESSION_REVOKED' | 'DEVICE_KEY_MISMATCH' | 'TOKEN_INVALID' | 'TOKEN_EXPIRED' | 'UNKNOWN_401';
 export declare class PermanentAuthFailure extends Error {
     readonly code: PermanentAuthReason;
     constructor(code: PermanentAuthReason, message: string);

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

@@ -0,0 +1,90 @@
+/**
+ * cliHandoffWire.ts — the ONE declaration of the CLI↔daemon hand-off wire
+ * contracts, shared by the daemon (writer/server) and the CLI (reader).
+ *
+ * Two contracts live here:
+ *
+ *   1. The hand-off descriptor file (`descriptor.json` on Dedicated guests,
+ *      `daemon-island.<profile>.json` on laptops). Until now the shape was
+ *      declared twice — `DedicatedCliHandoffDescriptor` daemon-side and
+ *      `LocalBootstrap` CLI-side — two type declarations for one file format,
+ *      the same drift disease `sessionPermissionAuthority` fixed.
+ *   2. The broker-mode redeem exchange: `POST /v1/auth/cli-handoff-token`
+ *      request/response plus its error codes.
+ *
+ * Readers stay loose (unknown fields ignored, absent `handoffModes` reads as
+ * refresh-family-only) so a new field never breaks an older peer; writers
+ * must produce the full shape.
+ */
+/**
+ * What a caller may redeem the descriptor secret for.
+ *  - `refresh_family`: the legacy durable mint (90-day cli-scope family).
+ *  - `access_token`:   broker mode — a short-lived access token from a
+ *                      daemon-owned family; nothing durable leaves the daemon.
+ */
+export declare const CLI_HANDOFF_MODES: readonly ["refresh_family", "access_token"];
+export type CliHandoffMode = (typeof CLI_HANDOFF_MODES)[number];
+/** Broker-mode redeem route on the daemon's loopback server. */
+export declare const CLI_HANDOFF_TOKEN_PATH = "/v1/auth/cli-handoff-token";
+/** Error codes this contract emits. String literals so both ends compare
+ *  without importing a symbol they may not have. */
+export declare const CLI_HANDOFF_TOKEN_ERROR_UNAVAILABLE = "HANDOFF_TOKEN_UNAVAILABLE";
+/** Emitted by the LEGACY /v1/auth/cli-handoff route when a hand-off-secret
+ *  caller asks for a refresh family the daemon no longer mints for it. */
+export declare const CLI_HANDOFF_ERROR_BROKER_ONLY = "HANDOFF_BROKER_ONLY";
+/**
+ * The descriptor file format. `version` is absent on the oldest island files
+ * and `1` on the first dedicated-guest descriptors; `handoffModes` first
+ * appears at version 2. Every field the CLI needs to dial is validated; the
+ * rest ride along untyped.
+ */
+export interface CliHandoffDescriptor {
+    version?: number;
+    pid?: number;
+    daemonId?: string;
+    host?: string;
+    port?: number;
+    /** Base64 handshake secret — hand-off-only on guests, island on laptops. */
+    secret?: string;
+    /** Server URL the daemon is authenticated against. Older daemons omit it;
+     *  readers refuse to broker without it (never mint against an unknown
+     *  server). */
+    serverUrl?: string;
+    /** Daemon-authored epoch counter; bumped when the descriptor is republished. */
+    epoch?: number;
+    handoffModes?: CliHandoffMode[];
+}
+/**
+ * Parse an untrusted descriptor JSON value. Returns null when the fields the
+ * caller cannot proceed without — host, port, secret — are absent or
+ * mistyped. Unknown fields and future `version` values are tolerated: the
+ * reader ignores them, which is what makes additive evolution safe.
+ */
+export declare function parseCliHandoffDescriptor(value: unknown): CliHandoffDescriptor | null;
+/**
+ * Untrusted `handoffModes` input → known literals only, deduped. An
+ * unrecognized future mode is dropped rather than widening by coercion.
+ */
+export declare function normalizeHandoffModes(value: unknown): CliHandoffMode[];
+/**
+ * The versioned-default rule: a descriptor that never declares modes offers
+ * only the durable mint it has always offered. Mode negotiation is purely
+ * additive — a daemon advertises the new mode, it never un-advertises the
+ * old one by accident.
+ */
+export declare function advertisedHandoffModes(d: CliHandoffDescriptor): CliHandoffMode[];
+export declare function descriptorOffersAccessToken(d: CliHandoffDescriptor): boolean;
+export interface CliHandoffTokenRequest {
+    /** Bypass the daemon broker's cached token (the 401-recovery path). */
+    forceRefresh?: boolean;
+}
+export interface CliHandoffTokenResponse {
+    accessToken: string;
+    /** Absolute expiry in ms since epoch, when the daemon knows it. */
+    accessExpiresAt?: number;
+    /** Server the minted credential belongs to — lets the caller verify it is
+     *  about to use a token for the API it thinks it is talking to. */
+    serverUrl?: string;
+}
+/** Parse the redeem response; null when the token itself is absent. */
+export declare function parseCliHandoffTokenResponse(value: unknown): CliHandoffTokenResponse | null;

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

@@ -0,0 +1,105 @@
+/**
+ * cliHandoffWire.ts — the ONE declaration of the CLI↔daemon hand-off wire
+ * contracts, shared by the daemon (writer/server) and the CLI (reader).
+ *
+ * Two contracts live here:
+ *
+ *   1. The hand-off descriptor file (`descriptor.json` on Dedicated guests,
+ *      `daemon-island.<profile>.json` on laptops). Until now the shape was
+ *      declared twice — `DedicatedCliHandoffDescriptor` daemon-side and
+ *      `LocalBootstrap` CLI-side — two type declarations for one file format,
+ *      the same drift disease `sessionPermissionAuthority` fixed.
+ *   2. The broker-mode redeem exchange: `POST /v1/auth/cli-handoff-token`
+ *      request/response plus its error codes.
+ *
+ * Readers stay loose (unknown fields ignored, absent `handoffModes` reads as
+ * refresh-family-only) so a new field never breaks an older peer; writers
+ * must produce the full shape.
+ */
+/**
+ * What a caller may redeem the descriptor secret for.
+ *  - `refresh_family`: the legacy durable mint (90-day cli-scope family).
+ *  - `access_token`:   broker mode — a short-lived access token from a
+ *                      daemon-owned family; nothing durable leaves the daemon.
+ */
+export const CLI_HANDOFF_MODES = ['refresh_family', 'access_token'];
+/** Broker-mode redeem route on the daemon's loopback server. */
+export const CLI_HANDOFF_TOKEN_PATH = '/v1/auth/cli-handoff-token';
+/** Error codes this contract emits. String literals so both ends compare
+ *  without importing a symbol they may not have. */
+export const CLI_HANDOFF_TOKEN_ERROR_UNAVAILABLE = 'HANDOFF_TOKEN_UNAVAILABLE';
+/** Emitted by the LEGACY /v1/auth/cli-handoff route when a hand-off-secret
+ *  caller asks for a refresh family the daemon no longer mints for it. */
+export const CLI_HANDOFF_ERROR_BROKER_ONLY = 'HANDOFF_BROKER_ONLY';
+/**
+ * Parse an untrusted descriptor JSON value. Returns null when the fields the
+ * caller cannot proceed without — host, port, secret — are absent or
+ * mistyped. Unknown fields and future `version` values are tolerated: the
+ * reader ignores them, which is what makes additive evolution safe.
+ */
+export function parseCliHandoffDescriptor(value) {
+    if (value == null || typeof value !== 'object')
+        return null;
+    const v = value;
+    if (typeof v.host !== 'string' || v.host.length === 0)
+        return null;
+    if (typeof v.port !== 'number' || !Number.isInteger(v.port) || v.port <= 0)
+        return null;
+    if (typeof v.secret !== 'string' || v.secret.length === 0)
+        return null;
+    return {
+        ...(typeof v.version === 'number' ? { version: v.version } : {}),
+        ...(typeof v.pid === 'number' ? { pid: v.pid } : {}),
+        ...(typeof v.daemonId === 'string' ? { daemonId: v.daemonId } : {}),
+        host: v.host,
+        port: v.port,
+        secret: v.secret,
+        ...(typeof v.serverUrl === 'string' ? { serverUrl: v.serverUrl } : {}),
+        ...(typeof v.epoch === 'number' ? { epoch: v.epoch } : {}),
+        ...(Array.isArray(v.handoffModes)
+            ? { handoffModes: normalizeHandoffModes(v.handoffModes) }
+            : {}),
+    };
+}
+/**
+ * Untrusted `handoffModes` input → known literals only, deduped. An
+ * unrecognized future mode is dropped rather than widening by coercion.
+ */
+export function normalizeHandoffModes(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const m of value) {
+        if (CLI_HANDOFF_MODES.includes(m) &&
+            !out.includes(m)) {
+            out.push(m);
+        }
+    }
+    return out;
+}
+/**
+ * The versioned-default rule: a descriptor that never declares modes offers
+ * only the durable mint it has always offered. Mode negotiation is purely
+ * additive — a daemon advertises the new mode, it never un-advertises the
+ * old one by accident.
+ */
+export function advertisedHandoffModes(d) {
+    const declared = normalizeHandoffModes(d.handoffModes);
+    return declared.length > 0 ? declared : ['refresh_family'];
+}
+export function descriptorOffersAccessToken(d) {
+    return advertisedHandoffModes(d).includes('access_token');
+}
+/** Parse the redeem response; null when the token itself is absent. */
+export function parseCliHandoffTokenResponse(value) {
+    if (value == null || typeof value !== 'object')
+        return null;
+    const v = value;
+    if (typeof v.accessToken !== 'string' || v.accessToken.length === 0)
+        return null;
+    return {
+        accessToken: v.accessToken,
+        ...(typeof v.accessExpiresAt === 'number' ? { accessExpiresAt: v.accessExpiresAt } : {}),
+        ...(typeof v.serverUrl === 'string' ? { serverUrl: v.serverUrl } : {}),
+    };
+}

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

@@ -21,6 +21,8 @@ type DisabledReason = 'kek_unavailable' | 'init_failed' | 'platform_unsupported'
 export declare function __setStateForTest(next: CredEnvelopeState): CredEnvelopeState;
 /** @internal Test seam — read state for assertions. */
 export declare function __getStateForTest(): CredEnvelopeState;
+/** @internal Test seam — each spec owns its warn-dedupe horizon. */
+export declare function __clearWarnDedupeForTest(): void;
 /**
  * Initialize the envelope path. Idempotent — second call when state is
  * non-uninit returns immediately.

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

@@ -123,7 +123,21 @@ function atomicWrite0600(target, value) {
  * The event name passed in is the FULLY-QUALIFIED `cred_envelope.*` form
  * because daemon-side telemetry consumers (`event-log.ts`, dashboards,
  * spec assertions) key off the prefixed name. Do not strip the prefix.
+ *
+ * Identical failure warnings hit the logger only once per process.
+ * Telemetry still records every occurrence — the dedupe exists because a
+ * single unreadable envelope produced the same warning once per stored
+ * field (token, refresh token, expiry…), which read to users as three
+ * crashes rather than one stale credential (OSK-12074). The signature is
+ * event + kek identity + message, so a genuinely different failure mode
+ * still gets its own line.
  */
+const warnedSignatures = new Set();
+const MAX_WARNED_SIGNATURES = 64;
+/** @internal Test seam — each spec owns its warn-dedupe horizon. */
+export function __clearWarnDedupeForTest() {
+    warnedSignatures.clear();
+}
 function emit(eventName, success, metadata) {
     emitAuthTelemetry({
         timestamp: new Date().toISOString(),
@@ -132,7 +146,13 @@ function emit(eventName, success, metadata) {
         metadata: { event: eventName, ...metadata },
     });
     if (!success) {
-        getAuthLogger().warn(`[credEnvelope] ${eventName}`, metadata);
+        const signature = `${eventName}:${metadata.kekId ?? ''}:${metadata.kekKind ?? ''}:${metadata.message ?? ''}`;
+        if (!warnedSignatures.has(signature)) {
+            if (warnedSignatures.size >= MAX_WARNED_SIGNATURES)
+                warnedSignatures.clear();
+            warnedSignatures.add(signature);
+            getAuthLogger().warn(`[credEnvelope] ${eventName}`, metadata);
+        }
     }
 }
 // ---------------------------------------------------------------------------
@@ -745,6 +765,10 @@ export function maybeDecryptOnRead(stored) {
                 kekId: _state.kekId,
                 kekKind: _state.kekKind,
                 message: err?.message ?? 'unknown',
+                // The crypto error alone reads as a crash; the actionable truth is
+                // that this stored credential is unreadable by THIS binary (usually
+                // a signing-identity or profile drift) and re-login rebuilds it.
+                hint: 'stored credential is unreadable on this machine — signing in again rebuilds it',
             });
             return { plaintext: null, needsMigration: false };
         }

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

@@ -0,0 +1,47 @@
+/**
+ * credentialSession.ts — the shared credential-lifecycle kernel (policy half).
+ *
+ * A credential lifecycle is policy × mechanism. The policy — serve a cached
+ * token until its expiry-skew window, collapse concurrent acquires onto one
+ * in-flight operation, invalidate on a resource-side 401 — is identical for
+ * every surface and was being re-implemented per consumer (task token-broker,
+ * delegated-cli redemption, the human CLI refresh path). The mechanism —
+ * WHERE the durable secret lives and HOW a token is acquired — legitimately
+ * differs (in-memory daemon family vs file+envelope+lock vs loopback redeem)
+ * and stays behind the `acquire` seam.
+ *
+ * Deliberately thin: no persistence, no retry policy, no logging. Callers
+ * own their store and their error surfaces; this owns the cache/single-
+ * flight/invalidate invariants so they cannot drift between surfaces.
+ */
+/** What an acquire returns. `expiresAtMs` absent means "no known expiry" —
+ *  the token is served until `invalidate()` or an acquire replaces it. */
+export interface AcquiredCredential {
+    accessToken: string;
+    /** Absolute expiry in ms since epoch, when the issuer tells us. */
+    expiresAtMs?: number;
+}
+export interface CredentialSessionOptions {
+    /**
+     * The mechanism. Called with `forceRefresh: true` when the caller asked to
+     * bypass the cache (the 401-recovery path) — implementations should renew
+     * rather than serve their own cache. A rejected promise propagates to every
+     * waiter and is never cached.
+     */
+    acquire: (forceRefresh: boolean) => Promise<AcquiredCredential>;
+    /** Serve the cached token until this many ms before expiry. Default 30s. */
+    skewMs?: number;
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+export interface CredentialSession {
+    /**
+     * Resolves a usable access token: the cached one while it is inside its
+     * freshness window, otherwise a single shared acquire. `forceRefresh`
+     * discards the cache first (use after a resource 401).
+     */
+    getToken(forceRefresh?: boolean): Promise<string>;
+    /** Drop the cached token; the next getToken() acquires. */
+    invalidate(): void;
+}
+export declare function createCredentialSession(opts: CredentialSessionOptions): CredentialSession;