@skrr-ai/cli 0.1.49 → 0.1.51

package/dist/lib/auth-failure.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * auth-failure.ts — say WHY a request was refused on authentication (OSK-12116).
+ *
+ * A 401 reaches the CLI after its own renewal has already failed: the access
+ * token expired, the refresh was refused, and the retry went out with the dead
+ * token. The server's answer to that retry is `TOKEN_EXPIRED`, which is true and
+ * useless — the expiry is routine, the refusal to RENEW is the fault, and it was
+ * visible only as an `[auth-core warn]` line on stderr.
+ *
+ * auth-core latches every permanent refresh refusal (`needs-reauth.json`, the
+ * same record `skrr whoami` prints as "Refresh state"). This module reads that
+ * latch and turns it into the sentence the error should have carried.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeRefreshRefusal = describeRefreshRefusal;
+/**
+ * Explain one refresh refusal in terms of what the reader can do about it.
+ * Returns null when there is no latched refusal, so the caller keeps its
+ * generic wording rather than inventing a cause.
+ */
+function describeRefreshRefusal(refusal, opts) {
+    if (!refusal?.reason)
+        return null;
+    const { bin } = opts;
+    const code = refusal.reason;
+    const said = refusal.message ? ` (${code}: ${refusal.message})` : ` (${code})`;
+    const relogin = `Run \`${bin} login\` to sign in again.`;
+    const message = refusal.message ?? '';
+    // The row the stored refresh token belongs to was minted for a different CLI
+    // identity than the one this config presents. The keychain slot is keyed by
+    // profile, while the CLI ID lives in the config directory — so a second skrr
+    // configuration on this machine (a different HOME or config dir sharing the
+    // same login Keychain) can write this profile's credential under its own ID.
+    // Observed: a token minted for `cli_devin_dogfood` sitting in the default
+    // profile's slot.
+    if (/bound to a different daemon/i.test(message)) {
+        return {
+            code,
+            message: `This profile's stored sign-in could not be renewed${said}. The credential in its ` +
+                `Keychain slot was issued to a different CLI identity than this one` +
+                `${opts.cliId ? ` (${opts.cliId})` : ''} — usually another skrr configuration on this ` +
+                `machine (a different HOME or config directory) signed in and wrote over it. ${relogin}`,
+        };
+    }
+    if (code === 'SESSION_REVOKED') {
+        return {
+            code,
+            message: `This sign-in was revoked${said}. Signing out elsewhere revokes it, and so does ` +
+                `revoking a daemon that brokered it (\`${bin} login\` without a browser signs in ` +
+                `through this machine's daemon). ${relogin}`,
+        };
+    }
+    if (code === 'REFRESH_REUSED') {
+        return {
+            code,
+            message: `This sign-in was ended because its refresh token was presented twice${said}; the ` +
+                `server treats that as possible theft and revokes the whole family. ${relogin}`,
+        };
+    }
+    return {
+        code,
+        message: `This sign-in could not be renewed${said}. ${relogin}`,
+    };
+}

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, CommitmentRunPermissions } 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, };
@@ -99,7 +99,27 @@ export type CommitmentPreflightReport = {
         suppressedBy?: string | null;
         [key: string]: unknown;
     };
+    /** Whose permissions a run uses (OSK-11975). Absent from older servers. */
+    permissions?: CommitmentRunPermissions | null;
+    /** `retired` names the fence fields OSK-11975 made inert (OSK-12065). */
+    execution?: {
+        retired?: string[];
+        retiredReason?: string;
+    } & Record<string, unknown>;
 };
+/**
+ * The lines every Commitment read surface prints for "whose permissions does a
+ * run use?" — `show`, `effective-policy` and `preflight` share it so the three
+ * cannot phrase it three ways (OSK-12065). The sentence and the warnings are
+ * the server's; this only lays them out. `null` (an older server that does not
+ * report it) prints nothing rather than a guess.
+ */
+export declare function permissionLines(permissions: CommitmentRunPermissions | null | undefined): string[];
+/**
+ * One line naming fields that are still in the JSON but decide nothing any
+ * more. Deprecation, not removal: `--json` keeps them for scripts.
+ */
+export declare function retiredFieldsLine(retired: string[] | undefined, reason: string | undefined): string | null;
 /**
  * A Commitment Pack's readiness receipt.
  *
@@ -351,6 +371,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 +786,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

@@ -4,6 +4,8 @@ exports.COMMITMENT_CLI_EVALUATORS = exports.COMMITMENT_CREATE_KEYS = exports.COM
 exports.storedAutonomyModeForAuthoring = storedAutonomyModeForAuthoring;
 exports.authoringAutonomyModeForStored = authoringAutonomyModeForStored;
 exports.commitmentAutonomyLabel = commitmentAutonomyLabel;
+exports.permissionLines = permissionLines;
+exports.retiredFieldsLine = retiredFieldsLine;
 exports.readCommitmentAgentDirective = readCommitmentAgentDirective;
 exports.normalizeCreateBody = normalizeCreateBody;
 exports.parseCommitmentConcurrencyLimit = parseCommitmentConcurrencyLimit;
@@ -26,6 +28,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;
@@ -107,6 +111,33 @@ function commitmentAutonomyLabel(mode) {
  */
 exports.MIN_COMMITMENT_INTERVAL_MS = 60_000;
 exports.MAX_COMMITMENT_INTERVAL_MS = 365 * 24 * 60 * 60 * 1000;
+/**
+ * The lines every Commitment read surface prints for "whose permissions does a
+ * run use?" — `show`, `effective-policy` and `preflight` share it so the three
+ * cannot phrase it three ways (OSK-12065). The sentence and the warnings are
+ * the server's; this only lays them out. `null` (an older server that does not
+ * report it) prints nothing rather than a guess.
+ */
+function permissionLines(permissions) {
+    if (!permissions?.summary)
+        return [];
+    const lines = [`Permissions: ${permissions.summary}`];
+    for (const warning of permissions.warnings || []) {
+        lines.push(`Warning: ${warning.message}`);
+        if (warning.fix)
+            lines.push(`  Fix: ${warning.fix}`);
+    }
+    return lines;
+}
+/**
+ * One line naming fields that are still in the JSON but decide nothing any
+ * more. Deprecation, not removal: `--json` keeps them for scripts.
+ */
+function retiredFieldsLine(retired, reason) {
+    if (!Array.isArray(retired) || !retired.length)
+        return null;
+    return `Retired fields (no effect): ${retired.join(', ')}${reason ? ` — ${reason}` : ''}`;
+}
 function base(id) {
     return `/api/commitments/${encodeURIComponent(id)}`;
 }
@@ -236,6 +267,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)),
@@ -1007,6 +1042,11 @@ function describeWakeDecision(check) {
     if (verdict === 'skipped') {
         const reason = typeof entry.reason === 'string' ? entry.reason : '';
         if (reason === 'posture_does_not_admit_agent_run') {
+            // The server names the commonest cause on the check's `stop`: nothing
+            // was open to act on. "record_only" alone read as a setting to change
+            // when the remedy was to give the Commitment some work (OSK-12090).
+            if (check.stop?.reason === 'no_open_loop')
+                return 'no — nothing open';
             const posture = typeof entry.posture === 'string' ? entry.posture : '';
             return posture ? `no — ${posture}` : 'no — posture';
         }
@@ -1160,23 +1200,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/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;
@@ -117,10 +138,16 @@ export interface DaemonBrokerFailure {
      * the daemon".
      */
     daemonServerUrl?: string;
+    /**
+     * For `base_url_mismatch` found locally: the descriptor file that named
+     * `daemonServerUrl`, so a message can say what was read rather than assert
+     * where "the" daemon is logged in (OSK-12117).
+     */
+    descriptorPath?: string;
 }
 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 +178,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
@@ -187,6 +230,14 @@ export declare function resolveBootstrapCandidatePaths(profile?: string): string
 export declare const DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR = "/run/skrr-dedicated-runtime/cli-handoff/descriptor.json";
 /** Where the cli-handoff broker looks, in order. */
 export declare function resolveCliHandoffCandidatePaths(profile?: string): string[];
+/**
+ * The island files that belong to exactly `profile` — its canonical path and
+ * the pre-rename darwin location — and never another profile's. The broker's
+ * candidate list for `default` deliberately falls through to any running
+ * profile, which is right for borrowing a credential and wrong for naming
+ * which daemon a profile's status describes (OSK-12102).
+ */
+export declare function resolveExactProfileBootstrapPaths(profile?: string): string[];
 /**
  * Resolve the first live daemon bootstrap for a profile. Message-intent
  * submission reuses the same authenticated loopback discovery as the login
@@ -214,10 +265,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 +376,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.