@skrr-ai/cli 0.1.48 → 0.1.50

package/dist/lib/api-fetch.js

@@ -42,6 +42,7 @@ const idempotency_scope_1 = require("./idempotency-scope");
 const node_adapter_1 = require("./node-adapter");
 const refresh_1 = require("./refresh");
 const delegated_cli_1 = require("./delegated-cli");
+const daemonBroker_1 = require("./daemonBroker");
 const workspace_header_1 = require("./workspace-header");
 const non_json_response_1 = require("./non-json-response");
 class ApiFetchError extends Error {
@@ -191,6 +192,24 @@ async function apiFetch(pathOrUrl, opts = {}) {
             res = await fetchWithCredential(cred);
         }
     }
+    else if (res.status === 401 &&
+        (0, daemonBroker_1.isBrokeredHandoffToken)(cred.token) &&
+        !isAuthEndpoint(pathOrUrl)) {
+        // Broker-mode hand-off credential: nothing was persisted, so there is no
+        // stored family for `ensureFreshCliCredential` to rotate. Re-redeem over
+        // loopback once (forceRefresh bypasses the daemon's cached token) and
+        // retry once — the same recovery contract the delegated path has.
+        const fresh = await (0, daemonBroker_1.redeemBrokeredHandoffToken)(true);
+        if (fresh?.accessToken) {
+            cred = {
+                token: fresh.accessToken,
+                source: 'env-token',
+                kind: (0, credential_resolver_1.kindOf)(fresh.accessToken),
+            };
+            (0, node_adapter_1.setAdapterCredentialOverride)(cred);
+            res = await fetchWithCredential(cred);
+        }
+    }
     else if (res.status === 401 && !autonomousCredential && !isAuthEndpoint(pathOrUrl)) {
         const fresh = await (0, refresh_1.ensureFreshCliCredential)({ credential: cred, force: true });
         if (fresh.refreshed && fresh.credential.token) {

package/dist/lib/auth-storage.d.ts

@@ -21,6 +21,20 @@ export interface WriteOptions {
     /** Clear a stale needs-reauth latch after a server has issued fresh credentials. */
     clearReauth?: boolean;
 }
+/**
+ * File-backend-only read. Exported for the brokered-hand-off migration
+ * cleanup (`daemonBroker.maybeRetireStoredCliAuthFile`), which must inspect
+ * `~/.skrr/cli-auth.json` specifically — not the keychain-preferred
+ * `readFromBackend()` — to prove the stored family's provenance before
+ * retiring it. Everything else should keep using `readFromBackend()`.
+ */
+export declare function readFromFile(): AuthBundle | null;
+/**
+ * Delete `~/.skrr/cli-auth.json` only (the keychain is untouched). Exported
+ * for the brokered-hand-off migration cleanup; `skrr logout` continues to
+ * use `clearAllBackends()`.
+ */
+export declare function deleteFileBackend(): void;
 /**
  * Read the CLI's auth bundle from the preferred backend.
  *

package/dist/lib/auth-storage.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.backends = void 0;
+exports.readFromFile = readFromFile;
+exports.deleteFileBackend = deleteFileBackend;
 exports.readFromBackend = readFromBackend;
 exports.writeToBackend = writeToBackend;
 exports.clearAllBackends = clearAllBackends;
@@ -96,6 +98,13 @@ function authFilePath() {
 // ---------------------------------------------------------------------
 // File backend
 // ---------------------------------------------------------------------
+/**
+ * File-backend-only read. Exported for the brokered-hand-off migration
+ * cleanup (`daemonBroker.maybeRetireStoredCliAuthFile`), which must inspect
+ * `~/.skrr/cli-auth.json` specifically — not the keychain-preferred
+ * `readFromBackend()` — to prove the stored family's provenance before
+ * retiring it. Everything else should keep using `readFromBackend()`.
+ */
 function readFromFile() {
     const p = authFilePath();
     if (!fs.existsSync(p))
@@ -235,6 +244,11 @@ function writeToFile(bundle) {
         throw err;
     }
 }
+/**
+ * Delete `~/.skrr/cli-auth.json` only (the keychain is untouched). Exported
+ * for the brokered-hand-off migration cleanup; `skrr logout` continues to
+ * use `clearAllBackends()`.
+ */
 function deleteFileBackend() {
     const p = authFilePath();
     try {

package/dist/lib/commitments.d.ts

@@ -17,7 +17,7 @@
  * "hold this state", derived from a Compass invariant — not authored here).
  */
 import { COMMITMENT_WATCHED_SOURCES, COMMITMENT_TEMPLATE_IDS, COMMITMENT_CADENCE_MODES, COMMITMENT_CADENCE_TIME_PATTERN, COMMITMENT_CADENCE_MAX_TIMES, COMMITMENT_AUTONOMY_MODES, COMMITMENT_EXECUTION_ISOLATION_MODES, COMMITMENT_STATUSES, COMMITMENT_KIND_VALUES } from '@skrr-ai/data-provider';
-import type { CommitmentCheck, CommitmentChecksResponse, Commitment, CommitmentActionProposal, CommitmentListResponse, CommitmentPlanResponse, CommitmentStatusResponse, CommitmentWorkLink, CommitmentExecutionReceiptListResponse, CommitmentExecutionReceiptQuarterlyMetricsResponse, CommitmentCapabilitySource, CommitmentDeliveryPatchResponse, CommitmentDeliveryBundleResponse } from '@skrr-ai/data-provider';
+import type { CommitmentCheck, CommitmentChecksResponse, Commitment, CommitmentActionProposal, CommitmentListResponse, CommitmentPlanResponse, CommitmentStatusResponse, CommitmentWorkLink, CommitmentExecutionReceiptListResponse, CommitmentExecutionReceiptQuarterlyMetricsResponse, CommitmentCapabilitySource, CommitmentDeliveryPatchResponse, CommitmentDeliveryBundleResponse, CommitmentCyclesResponse, CommitmentExplanationResponse } from '@skrr-ai/data-provider';
 import { withQuery } from './triggers';
 export { COMMITMENT_WATCHED_SOURCES, COMMITMENT_TEMPLATE_IDS, COMMITMENT_CADENCE_MODES, COMMITMENT_CADENCE_TIME_PATTERN, COMMITMENT_CADENCE_MAX_TIMES, COMMITMENT_STATUSES, COMMITMENT_KIND_VALUES, };
 export type { CommitmentCheck, CommitmentChecksResponse, Commitment, CommitmentActionProposal, CommitmentListResponse, CommitmentPlanResponse, CommitmentStatusResponse, CommitmentWorkLink, };
@@ -351,6 +351,13 @@ export declare const commitmentApi: {
         limit?: number;
         cursor?: string;
     }) => Promise<Record<string, unknown>>;
+    /** One Cycle per Check, newest first — the unit a person reads (D8). */
+    cycles: (id: string, query?: {
+        limit?: number;
+        cursor?: string;
+    }) => Promise<CommitmentCyclesResponse>;
+    /** The latest Cycle walked as six questions; the first "no" is where it stopped. */
+    explain: (id: string) => Promise<CommitmentExplanationResponse>;
     ledger: (id: string, query?: Record<string, string | number | undefined>) => Promise<Record<string, unknown>>;
     wakeCapabilities: (id: string) => Promise<CommitmentWakeCapabilities>;
     dailyMetrics: (id: string, query?: {
@@ -759,8 +766,16 @@ export declare function renderCheckList(checks: CommitmentCheckView[], log: (lin
 type ReadModelRecord = Record<string, unknown>;
 /** Human view for `commitments ledger`; JSON remains the automation surface. */
 export declare function renderCommitmentLedger(ledger: ReadModelRecord, log: (line: string) => void): void;
-/** Human view for the ordered commitment trace. */
 export declare function renderCommitmentTrace(trace: ReadModelRecord, log: (line: string) => void): void;
+/**
+ * One line per Cycle:
+ * `09-22 12:04  ● stopped    act  commitment_execution_budget_exhausted — Raise maxRunsPerDay…`
+ * A run that failed is named under its Cycle with who has to move (machine
+ * or model), because that is the next question every reader asks.
+ */
+export declare function formatCommitmentCycles(page: Partial<CommitmentCyclesResponse>): string[];
+/** The six questions for the latest Cycle, the first ✗ carrying its fix. */
+export declare function formatCommitmentExplanation(explanation: Partial<CommitmentExplanationResponse>): string[];
 /**
  * Print the continuation hint for a paged `object:'list'` response — the line
  * that makes history beyond the newest page reachable instead of invisible.

package/dist/lib/commitments.js

@@ -26,6 +26,8 @@ exports.describeWakeDecision = describeWakeDecision;
 exports.renderCheckList = renderCheckList;
 exports.renderCommitmentLedger = renderCommitmentLedger;
 exports.renderCommitmentTrace = renderCommitmentTrace;
+exports.formatCommitmentCycles = formatCommitmentCycles;
+exports.formatCommitmentExplanation = formatCommitmentExplanation;
 exports.renderListPageHint = renderListPageHint;
 exports.renderCommitmentObservations = renderCommitmentObservations;
 exports.renderCommitmentHypotheses = renderCommitmentHypotheses;
@@ -236,6 +238,10 @@ exports.commitmentApi = {
     /** Un-delete. Returns the Commitment PAUSED, never active. */
     restore: (id) => data_provider_1.request.post(`${base(id)}/restore`, {}),
     trace: (id, query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/trace`, query)),
+    /** One Cycle per Check, newest first — the unit a person reads (D8). */
+    cycles: (id, query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/cycles`, query)),
+    /** The latest Cycle walked as six questions; the first "no" is where it stopped. */
+    explain: (id) => data_provider_1.request.get(`${base(id)}/explain`),
     ledger: (id, query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/ledger`, query)),
     wakeCapabilities: (id) => data_provider_1.request.get(`${base(id)}/wake-capabilities`),
     dailyMetrics: (id, query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/daily-metrics`, query)),
@@ -1160,23 +1166,131 @@ function renderCommitmentLedger(ledger, log) {
     }
 }
 /** Human view for the ordered commitment trace. */
+/**
+ * `question:reason` for a trace event's server-derived stop — which of the six
+ * questions (wake, fresh, turn, think, act, reach) the wake stopped at. `none`
+ * means an Agent turn was dispatched. Blank when the event carries no stop.
+ */
+function stopCell(item) {
+    const detail = item.detail;
+    const stop = detail && typeof detail === 'object' ? detail.stop : undefined;
+    if (!stop || typeof stop !== 'object')
+        return '';
+    const { question, gate, reason } = stop;
+    if (typeof question !== 'string')
+        return '';
+    let why = '';
+    if (typeof reason === 'string' && reason)
+        why = reason;
+    else if (typeof gate === 'string')
+        why = gate;
+    return why ? `${question}: ${why}` : question;
+}
 function renderCommitmentTrace(trace, log) {
     const events = records(trace.events);
     renderRows(events.map((item) => ({
         at: text(firstValue(item, ['occurredAt', 'createdAt', 'startedAt'])),
         type: text(firstValue(item, ['type', 'kind'])),
         status: text(item.status),
+        stop: stopCell(item),
         summary: text(firstValue(item, ['summary', 'reason', 'title']), ''),
     })), [
         { key: 'at', header: 'AT', maxWidth: 24 },
         { key: 'type', header: 'TYPE', maxWidth: 28 },
         { key: 'status', header: 'STATUS', maxWidth: 28 },
+        { key: 'stop', header: 'STOPPED AT', maxWidth: 48 },
         { key: 'summary', header: 'SUMMARY', maxWidth: 72 },
     ], 'No trace events recorded.', log);
     if (trace.has_more === true && trace.next_cursor) {
         log(`More events are available; continue with --cursor ${text(trace.next_cursor)}.`);
     }
 }
+const CYCLE_GLYPH = {
+    advanced: '✓',
+    stopped: '●',
+    quiet: '○',
+    in_flight: '◌',
+};
+/** `MM-DD HH:MM` in the reader's local time; `-` when the time is unknown. */
+function cycleTime(value) {
+    if (typeof value !== 'string')
+        return '-';
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return '-';
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+function cycleWake(cycle) {
+    const wake = cycle.wake || {};
+    if (wake.kind === 'fire')
+        return `${wake.source || 'trigger'} wake`;
+    return wake.source ? `${wake.kind} (${wake.source})` : String(wake.kind || '-');
+}
+/** What one Cycle came to, in a single line. */
+function cycleSummary(cycle) {
+    if (cycle.outcome === 'stopped' && cycle.stop) {
+        const { question, gate, reason, fix, detail } = cycle.stop;
+        return `${question}  ${reason || gate} — ${fix || detail || 'stopped'}`;
+    }
+    if (cycle.outcome === 'advanced') {
+        return cycle.advancementKinds?.length
+            ? cycle.advancementKinds.join(', ')
+            : 'applied an agent result';
+    }
+    if (cycle.outcome === 'in_flight') {
+        const runs = cycle.runs?.length || 0;
+        return runs ? `${runs} run(s) still going` : 'check still running';
+    }
+    return cycle.note || cycle.decision?.summary || cycle.decision?.posture || 'nothing to act on';
+}
+/**
+ * One line per Cycle:
+ * `09-22 12:04  ● stopped    act  commitment_execution_budget_exhausted — Raise maxRunsPerDay…`
+ * A run that failed is named under its Cycle with who has to move (machine
+ * or model), because that is the next question every reader asks.
+ */
+function formatCommitmentCycles(page) {
+    const cycles = Array.isArray(page.cycles) ? page.cycles : [];
+    if (!cycles.length)
+        return ['No cycles recorded yet.'];
+    const lines = [];
+    for (const cycle of cycles) {
+        const glyph = CYCLE_GLYPH[cycle.outcome] || '?';
+        lines.push(`${cycleTime(cycle.startedAt)}  ${glyph} ${String(cycle.outcome).padEnd(9)}  ${cycleWake(cycle).padEnd(18)}  ${cycleSummary(cycle)}`);
+        for (const run of cycle.runs || []) {
+            if (!['machine', 'contract', 'work'].includes(run.failureClass))
+                continue;
+            const owner = run.failureOwner === 'model' ? 'model' : run.failureOwner || 'work';
+            lines.push(`             run ${run.id} ${run.status} — ${owner}: ${run.failureCode || '-'}`);
+        }
+    }
+    if (page.has_more && page.next_cursor) {
+        lines.push(`More cycles are available; continue with --cursor ${page.next_cursor}.`);
+    }
+    return lines;
+}
+const ANSWER_GLYPH = { yes: '✓', no: '✗', 'n/a': '–' };
+/** The six questions for the latest Cycle, the first ✗ carrying its fix. */
+function formatCommitmentExplanation(explanation) {
+    const cycle = explanation.cycle;
+    const lines = [
+        cycle
+            ? `Latest cycle: ${cycleTime(cycle.startedAt)} ${cycle.outcome} (${cycle.id})`
+            : `No cycle yet (status: ${explanation.status || '-'})`,
+    ];
+    for (const answer of explanation.answers || []) {
+        lines.push(`  ${ANSWER_GLYPH[answer.answer] || '?'} ${answer.question}  ${answer.because}`);
+        if (answer.fix)
+            lines.push(`      Fix: ${answer.fix}`);
+    }
+    lines.push(!explanation.stoppedAt
+        ? 'Nothing stopped this cycle.'
+        : explanation.verdict === 'quiet'
+            ? `Chose to stay quiet at: ${explanation.stoppedAt}`
+            : `Stopped at: ${explanation.stoppedAt}`);
+    return lines;
+}
 /**
  * Print the continuation hint for a paged `object:'list'` response — the line
  * that makes history beyond the newest page reachable instead of invisible.

package/dist/lib/daemon-installer.d.ts

@@ -1,6 +1,6 @@
-import { type DaemonVersionManifest, type ReleaseKey } from '@skrr-ai/auth-core';
+import { isTrustedArtifactOrigin, type DaemonVersionManifest, type ReleaseKey } from '@skrr-ai/auth-core';
 /** Public CloudFront feed. Mirrors the daemon's own `CLOUDFRONT_FEED_BASE`. */
-export declare const DEFAULT_DAEMON_FEED_BASE = "https://updates.oversky.ai/daemon";
+export declare const DEFAULT_DAEMON_FEED_BASE = "https://updates.skrr.ai/daemon";
 /** Same override the daemon honours, so one env var steers both. */
 export declare const DAEMON_FEED_BASE_ENV = "OVERSKY_DAEMON_UPDATE_FEED_BASE";
 export type DaemonInstallFailureCode = 'unsupported_platform' | 'manifest_unreachable' | 'manifest_malformed' | 'manifest_unsigned' | 'platform_missing' | 'untrusted_artifact_origin' | 'download_failed' | 'checksum_mismatch' | 'artifact_unsigned' | 'write_failed';
@@ -44,10 +44,11 @@ export declare function daemonBinaryPath(env?: NodeJS.ProcessEnv): string;
 export declare function daemonPlatformKey(platform?: string, arch?: string): string | null;
 /**
  * True when `candidate` may serve an artifact for a feed rooted at `feedBase`.
- * Same rule as the daemon's `isTrustedArtifactOrigin`: a signed manifest still
- * does not get to point the download at another origin.
+ * The predicate is shared with the daemon's self-updater via
+ * `@skrr-ai/auth-core` — during the host transition a signed manifest may
+ * legitimately point at either update origin (see TRUSTED_FEED_ORIGINS there).
  */
-export declare function isTrustedArtifactOrigin(candidate: string, feedBase: string): boolean;
+export { isTrustedArtifactOrigin };
 /** Fetch `<feedBase>/latest/daemon-version.json` and verify its signature. */
 export declare function fetchVerifiedDaemonManifest(opts?: DaemonInstallOptions): Promise<{
     ok: true;

package/dist/lib/daemon-installer.js

@@ -3,11 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DAEMON_FEED_BASE_ENV = exports.DEFAULT_DAEMON_FEED_BASE = void 0;
+exports.isTrustedArtifactOrigin = exports.DAEMON_FEED_BASE_ENV = exports.DEFAULT_DAEMON_FEED_BASE = void 0;
 exports.daemonFeedBase = daemonFeedBase;
 exports.daemonBinaryPath = daemonBinaryPath;
 exports.daemonPlatformKey = daemonPlatformKey;
-exports.isTrustedArtifactOrigin = isTrustedArtifactOrigin;
 exports.fetchVerifiedDaemonManifest = fetchVerifiedDaemonManifest;
 exports.installDaemon = installDaemon;
 /**
@@ -63,8 +62,9 @@ const node_fs_1 = require("node:fs");
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const auth_core_1 = require("@skrr-ai/auth-core");
+Object.defineProperty(exports, "isTrustedArtifactOrigin", { enumerable: true, get: function () { return auth_core_1.isTrustedArtifactOrigin; } });
 /** Public CloudFront feed. Mirrors the daemon's own `CLOUDFRONT_FEED_BASE`. */
-exports.DEFAULT_DAEMON_FEED_BASE = 'https://updates.oversky.ai/daemon';
+exports.DEFAULT_DAEMON_FEED_BASE = 'https://updates.skrr.ai/daemon';
 /** Same override the daemon honours, so one env var steers both. */
 exports.DAEMON_FEED_BASE_ENV = 'OVERSKY_DAEMON_UPDATE_FEED_BASE';
 /** Refuse a manifest larger than this. It is a small JSON document. */
@@ -102,19 +102,6 @@ function daemonPlatformKey(platform = process.platform, arch = process.arch) {
     const key = `${platform}-${arch}`;
     return supported.has(key) ? key : null;
 }
-/**
- * True when `candidate` may serve an artifact for a feed rooted at `feedBase`.
- * Same rule as the daemon's `isTrustedArtifactOrigin`: a signed manifest still
- * does not get to point the download at another origin.
- */
-function isTrustedArtifactOrigin(candidate, feedBase) {
-    try {
-        return new URL(candidate).origin === new URL(feedBase).origin;
-    }
-    catch {
-        return false;
-    }
-}
 function fail(code, error) {
     return { ok: false, code, error };
 }
@@ -193,7 +180,7 @@ async function installDaemon(opts = {}) {
     if (!artifact?.url || !artifact.sha256) {
         return fail('platform_missing', `release ${manifest.version} publishes no artifact for ${platformKey}`);
     }
-    if (!isTrustedArtifactOrigin(artifact.url, feedBase)) {
+    if (!(0, auth_core_1.isTrustedArtifactOrigin)(artifact.url, feedBase)) {
         return fail('untrusted_artifact_origin', `manifest points ${platformKey} at ${artifact.url}, which is not on the feed's origin`);
     }
     const artifactVerdict = (0, auth_core_1.verifyArtifact)(platformKey, manifest.version, artifact, keys);

package/dist/lib/daemonBroker.d.ts

@@ -36,31 +36,25 @@
  * liveness with `process.kill(pid, 0)` to filter stale files left behind
  * by a force-killed daemon.
  */
+import { type CliHandoffDescriptor, type CliHandoffTokenResponse } from '@skrr-ai/auth-core/cli-handoff-wire';
 import { type AuthBackend } from './auth-storage';
 import { type CliConfig } from './config';
 /**
- * Wire-shape of the bootstrap file. Mirrors
- * `daemon/src/local-bootstrap.ts::LocalBootstrap`. Kept loose — fields
- * the CLI doesn't use are ignored, and a future addition (e.g. version
- * bump, new metadata) doesn't break this reader.
+ * Wire-shape of the bootstrap file — the shared declaration in
+ * `@skrr-ai/auth-core/cli-handoff-wire` (`CliHandoffDescriptor`), which the
+ * daemon's writers and this reader both parse against so the format cannot
+ * drift between two mirrored type declarations. `LocalBootstrap` stays the
+ * exported name so existing callers (`daemon-target`, `message-intent`,
+ * `dedicated-lease-command`) don't churn.
+ *
+ * Fields the CLI doesn't use are ignored by the parser, and a future
+ * addition (e.g. version bump, new metadata) doesn't break this reader.
+ * `handoffModes` (descriptor v2) advertises what the secret can redeem:
+ * absent reads as `['refresh_family']` — today's durable mint; a guest
+ * descriptor advertising `['access_token']` can only redeem short-lived
+ * access tokens from the daemon's in-memory broker.
  */
-export interface LocalBootstrap {
-    version?: number;
-    pid?: number;
-    daemonId?: string;
-    host?: string;
-    port?: number;
-    /** Base64 32-byte handshake secret. */
-    secret?: string;
-    /**
-     * Server URL the daemon is authenticated against (e.g.
-     * `https://oversky.ai` or `http://localhost:3080`). Daemons that
-     * pre-date the baseURL-match check do not write this field — the
-     * broker pre-flight then refuses to call so we never mint against
-     * an unknown server.
-     */
-    serverUrl?: string;
-}
+export type LocalBootstrap = CliHandoffDescriptor;
 /**
  * Normalize a base URL for equality comparison. Mirrors the daemon-side
  * `normalizeBaseUrl` in `daemon/src/auth/cliHandoff.ts` so both ends
@@ -94,6 +88,33 @@ export interface DaemonBrokerResult {
      * the file.
      */
     storedIn?: Exclude<AuthBackend, 'none'>;
+    /**
+     * False on the legacy durable-mint shape so `outcome.brokered === true`
+     * narrows the outcome union. A durable mint is never brokered.
+     */
+    brokered?: false;
+}
+/**
+ * Broker-mode success: the descriptor advertised `access_token` and the
+ * daemon's loopback token route (`POST /v1/auth/cli-handoff-token`) answered
+ * a short-lived cli-scope access token minted from a refresh family the
+ * DAEMON holds in memory.
+ *
+ * This outcome carries no `refreshToken`, no `cliId`, no `userId` — nothing
+ * credential-shaped may be persisted for it. `brokered: true` is the tag the
+ * persist path keys on to skip `writeToBackend` entirely; the token is used
+ * in-memory for this process only, and the next `skrr` invocation re-redeems
+ * over loopback.
+ */
+export interface DaemonBrokeredOutcome {
+    ok: true;
+    brokered: true;
+    accessToken: string;
+    /** Absolute expiry in epoch ms, when the daemon reports it. */
+    accessExpiresAt?: number;
+    /** Server the minted credential belongs to (daemon-reported, else the
+     *  descriptor's own `serverUrl`). */
+    serverUrl?: string;
 }
 /**
  * Explicit reasons the broker path could fail. These exist to keep the
@@ -101,7 +122,7 @@ export interface DaemonBrokerResult {
  * 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' | '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' | 'server_error' | 'network' | 'timeout' | 'unknown';
 export interface DaemonBrokerFailure {
     ok: false;
     reason: DaemonBrokerErrorReason;
@@ -120,7 +141,7 @@ export interface DaemonBrokerFailure {
 }
 export type DaemonBrokerOutcome = (DaemonBrokerResult & {
     ok: true;
-}) | DaemonBrokerFailure;
+}) | DaemonBrokeredOutcome | DaemonBrokerFailure;
 export interface DaemonBrokerOptions {
     /** Stable per-machine cliId the CLI wants the new refresh row bound to. */
     cliId: string;
@@ -151,6 +172,22 @@ export interface DaemonBrokerOptions {
     candidatePathsOverride?: readonly string[];
     /** Override total request timeout. Tests use a short value. */
     timeoutMs?: number;
+    /**
+     * Which advertised mode to prefer when a descriptor offers both
+     * (`handoffModes: ['access_token', 'refresh_family']`, the laptop island
+     * shape during transition):
+     *
+     *   - `'access_token'` — broker mode: redeem a short-lived access token
+     *     and hold it in memory only. Used by `maybeAutoBroker`: nothing
+     *     credential-shaped lands on disk and each `skrr` process re-redeems
+     *     over loopback.
+     *   - `'refresh_family'` (default) — the legacy durable mint. Used by
+     *     explicit `skrr login`: a human login still writes a real,
+     *     user-owned refresh family. A descriptor that advertises ONLY
+     *     `access_token` (the Dedicated guest shape) redeems brokered
+     *     regardless — its secret cannot mint a family at all.
+     */
+    preferHandoffMode?: 'access_token' | 'refresh_family';
 }
 /**
  * Compute the bootstrap file path. Exported for tests so they can assert
@@ -214,10 +251,60 @@ export declare function readBootstrap(filePath: string): LocalBootstrap | null;
  */
 export declare function attemptDaemonBrokerLogin(opts: DaemonBrokerOptions): Promise<DaemonBrokerOutcome>;
 /**
- * Convenience wrapper: run the broker call and, on success, persist the
- * returned bundle through the canonical Sky CLI auth backend (Keychain
- * on macOS, `cli-auth.json` elsewhere). Returns the same outcome shape
- * so the caller can branch on `ok`.
+ * True when `token` is the access token this process redeemed through the
+ * daemon's broker-mode hand-off. `api-fetch` uses this to pick the re-redeem
+ * recovery branch instead of the stored-family refresh (which would have
+ * nothing to rotate — brokered credentials are never persisted).
+ */
+export declare function isBrokeredHandoffToken(token: string | null | undefined): boolean;
+/**
+ * Re-redeem the brokered hand-off token — the 401-recovery path. The
+ * descriptor is re-read from disk when its source path is known, so a secret
+ * rotated by a daemon restart resolves to the fresh one. Returns null when
+ * this process holds no brokered credential or the redeem fails (the caller
+ * then surfaces the original 401).
+ */
+export declare function redeemBrokeredHandoffToken(forceRefresh?: boolean): Promise<CliHandoffTokenResponse | null>;
+/** @internal test seam — clears the module-scoped brokered credential. */
+export declare function __resetBrokeredHandoffForTest(): void;
+/**
+ * True when a live local descriptor advertises broker-mode access — i.e.
+ * this machine's CLI authority is platform-managed and `skrr logout` has no
+ * local credential to clear. Read-only: parses candidates, never redeems.
+ */
+export declare function findBrokeredHandoffDescriptor(profile?: string): LocalBootstrap | null;
+/**
+ * Migration cleanup: retire the refresh family a pre-broker-mode CLI
+ * generation persisted, now that this machine redeems access tokens from
+ * the daemon's in-memory broker.
+ *
+ * Provenance guard — locally we cannot tell a hand-off-minted family from a
+ * user's explicit `skrr login` family by shape (the distinguishing
+ * `daemonRefOverride` lives server-side). The safe rule, applied here:
+ * revoke + delete ONLY when all of these hold —
+ *
+ *   1. the descriptor that just redeemed IS the Dedicated Runtime guest
+ *      hand-off file (`/run/skrr-dedicated-runtime/...`),
+ *   2. `~/.skrr/cli-auth.json` reads cleanly and carries a refresh token,
+ *   3. its stored `serverOrigin` matches the descriptor's `serverUrl`.
+ *
+ * When provenance can't be proven the file is KEPT: an explicit `skrr login`
+ * on a guest is rare but real, and a stale extra family is bounded by the
+ * server's session cap and expires on its own. Best-effort throughout — a
+ * failed revoke still deletes the file (the whole point is that nothing
+ * credential-shaped should remain), and any failure leaves the working
+ * brokered credential untouched.
+ */
+export declare function maybeRetireStoredCliAuthFile(opts: {
+    descriptorPath?: string;
+    descriptorServerUrl?: string;
+}): Promise<void>;
+/**
+ * Convenience wrapper: run the broker call and, on a durable-mint success,
+ * persist the returned bundle through the canonical Sky CLI auth backend
+ * (Keychain on macOS, `cli-auth.json` elsewhere). A `brokered` outcome is
+ * returned WITHOUT persisting — that is the entire point of broker mode.
+ * Returns the same outcome shape so the caller can branch on `ok`/`brokered`.
  */
 export declare function attemptDaemonBrokerLoginAndPersist(opts: DaemonBrokerOptions): Promise<DaemonBrokerOutcome>;
 export interface MaybeAutoBrokerOptions {
@@ -275,10 +362,12 @@ export interface MaybeAutoBrokerResult {
  *   - `commandId` is in `AUTH_SELF_MANAGED_COMMANDS`
  *
  * Side effects:
- *   - Calls `attemptDaemonBrokerLoginAndPersist` which writes to the
- *     keychain / cli-auth.json on success (this is the whole point —
- *     subsequent commands read the persisted token via the normal
- *     resolver chain, no broker round-trip per command).
+ *   - Calls `attemptDaemonBrokerLoginAndPersist` with `preferHandoffMode:
+ *     '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
+ *     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
  *     presents the same id to the server's refresh rotator.