@skrr-ai/cli 0.1.49 → 0.1.51

package/dist/lib/daemonBroker.js

@@ -77,14 +77,23 @@ exports.resolveBootstrapPath = resolveBootstrapPath;
 exports.resolveProfileBootstrapPaths = resolveProfileBootstrapPaths;
 exports.resolveBootstrapCandidatePaths = resolveBootstrapCandidatePaths;
 exports.resolveCliHandoffCandidatePaths = resolveCliHandoffCandidatePaths;
+exports.resolveExactProfileBootstrapPaths = resolveExactProfileBootstrapPaths;
 exports.findLiveDaemonBootstrap = findLiveDaemonBootstrap;
 exports.readBootstrap = readBootstrap;
 exports.attemptDaemonBrokerLogin = attemptDaemonBrokerLogin;
+exports.isBrokeredHandoffToken = isBrokeredHandoffToken;
+exports.redeemBrokeredHandoffToken = redeemBrokeredHandoffToken;
+exports.__resetBrokeredHandoffForTest = __resetBrokeredHandoffForTest;
+exports.findBrokeredHandoffDescriptor = findBrokeredHandoffDescriptor;
+exports.maybeRetireStoredCliAuthFile = maybeRetireStoredCliAuthFile;
 exports.attemptDaemonBrokerLoginAndPersist = attemptDaemonBrokerLoginAndPersist;
 exports.maybeAutoBroker = maybeAutoBroker;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const os = __importStar(require("node:os"));
+const auth_core_1 = require("@skrr-ai/auth-core");
+const loopback_http_1 = require("@skrr-ai/auth-core/loopback-http");
+const cli_handoff_wire_1 = require("@skrr-ai/auth-core/cli-handoff-wire");
 const auth_storage_1 = require("./auth-storage");
 const config_1 = require("./config");
 const device_id_1 = require("./device-id");
@@ -132,6 +141,16 @@ function resolveProfileBootstrapPaths(primary, entryNames) {
         .map((name) => path.join(path.dirname(primary), name));
     return [primary, ...extras];
 }
+/**
+ * Legacy bootstrap directory (darwin): pre-rename daemons wrote under
+ * `~/Library/Application Support/OverSky/` while this reader looked under
+ * `skrr/` — a drift that silently killed island bootstrapping on macOS
+ * (OSK-12057). New daemons dual-write both; old daemons keep writing only
+ * `OverSky/`, so these stay consulted as fallbacks.
+ */
+function legacyDarwinBootstrapDir() {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'OverSky');
+}
 /**
  * List the bootstrap files that a Sky CLI may use for a local daemon
  * handoff. `default` stays first for backwards compatibility; any other
@@ -143,16 +162,31 @@ function resolveProfileBootstrapPaths(primary, entryNames) {
  */
 function resolveBootstrapCandidatePaths(profile = 'default') {
     const primary = resolveBootstrapPath(profile);
-    if (profile !== 'default')
-        return [primary];
+    if (profile !== 'default') {
+        const legacy = process.platform === 'darwin'
+            ? [path.join(legacyDarwinBootstrapDir(), `daemon-island.${profile}.json`)]
+            : [];
+        return [primary, ...legacy];
+    }
     try {
         if (process.platform === 'darwin') {
-            const dir = path.dirname(primary);
-            const entryNames = fs
-                .readdirSync(dir, { withFileTypes: true })
-                .filter((entry) => entry.isFile())
-                .map((entry) => entry.name);
-            return resolveProfileBootstrapPaths(primary, entryNames);
+            const candidates = [primary];
+            for (const dir of [path.dirname(primary), legacyDarwinBootstrapDir()]) {
+                let entryNames = [];
+                try {
+                    entryNames = fs
+                        .readdirSync(dir, { withFileTypes: true })
+                        .filter((entry) => entry.isFile())
+                        .map((entry) => entry.name);
+                }
+                catch {
+                    continue;
+                }
+                for (const p of resolveProfileBootstrapPaths(path.join(dir, 'daemon-island.default.json'), entryNames)) {
+                    candidates.push(p);
+                }
+            }
+            return [...new Set(candidates)];
         }
         const profilesDir = path.dirname(path.dirname(primary));
         const extras = fs
@@ -201,6 +235,20 @@ function resolveCliHandoffCandidatePaths(profile = 'default') {
 function legacyBootstrapPath() {
     return path.join(os.homedir(), '.skrr', 'daemon-island.json');
 }
+/**
+ * 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).
+ */
+function resolveExactProfileBootstrapPaths(profile = 'default') {
+    const primary = resolveBootstrapPath(profile);
+    if (process.platform === 'darwin') {
+        return [primary, path.join(legacyDarwinBootstrapDir(), `daemon-island.${profile}.json`)];
+    }
+    return profile === 'default' ? [primary, legacyBootstrapPath()] : [primary];
+}
 /**
  * Resolve the first live daemon bootstrap for a profile. Message-intent
  * submission reuses the same authenticated loopback discovery as the login
@@ -233,19 +281,25 @@ function readBootstrap(filePath) {
     catch {
         return null;
     }
-    let parsed;
+    let parsedJson;
     try {
-        parsed = JSON.parse(raw);
+        parsedJson = JSON.parse(raw);
     }
     catch {
         return null;
     }
-    if (parsed?.host !== '127.0.0.1' ||
-        typeof parsed?.port !== 'number' ||
-        !Number.isInteger(parsed.port) ||
-        parsed.port < 1 ||
+    // Shared wire parser (`@skrr-ai/auth-core/cli-handoff-wire`) validates the
+    // fields a caller cannot proceed without — host, port, secret — and
+    // tolerates unknown fields and future `version` values. The CLI's own
+    // checks below stay STRICTER on purpose: the broker is loopback-only, the
+    // port must be a real TCP port, and the secret is a fixed-width key.
+    const parsed = (0, cli_handoff_wire_1.parseCliHandoffDescriptor)(parsedJson);
+    if (!parsed)
+        return null;
+    if (parsed.host !== '127.0.0.1' ||
+        typeof parsed.port !== 'number' ||
         parsed.port > 65_535 ||
-        typeof parsed?.secret !== 'string' ||
+        typeof parsed.secret !== 'string' ||
         Buffer.from(parsed.secret, 'base64').length !== 32) {
         return null;
     }
@@ -283,9 +337,12 @@ async function attemptDaemonBrokerLogin(opts) {
             : resolveCliHandoffCandidatePaths(profile);
     // Bound candidates (their serverUrl matches this CLI) in order, then unbound
     // ones. Every usable candidate is kept, not just the first: see below.
+    // `sourcePath` rides along — the brokered-migration cleanup keys on whether
+    // the redeeming descriptor IS the Dedicated guest hand-off file.
     const usable = [];
     const unbound = [];
     let mismatchedBootstrap = null;
+    let mismatchedPath = null;
     for (const candidate of candidates) {
         const candidateBootstrap = readBootstrap(candidate);
         if (!candidateBootstrap)
@@ -295,15 +352,18 @@ async function attemptDaemonBrokerLogin(opts) {
             typeof opts.baseURL === 'string' &&
             opts.baseURL.length > 0 &&
             normalizeBaseUrl(opts.baseURL) !== normalizeBaseUrl(candidateBootstrap.serverUrl)) {
-            mismatchedBootstrap ??= candidateBootstrap;
+            if (!mismatchedBootstrap) {
+                mismatchedBootstrap = candidateBootstrap;
+                mismatchedPath = candidate;
+            }
             continue;
         }
         if (typeof candidateBootstrap.serverUrl !== 'string' ||
             candidateBootstrap.serverUrl.length === 0) {
-            unbound.push(candidateBootstrap);
+            unbound.push({ bootstrap: candidateBootstrap, sourcePath: candidate });
             continue;
         }
-        usable.push(candidateBootstrap);
+        usable.push({ bootstrap: candidateBootstrap, sourcePath: candidate });
     }
     usable.push(...unbound);
     if (usable.length === 0) {
@@ -311,8 +371,11 @@ async function attemptDaemonBrokerLogin(opts) {
             return {
                 ok: false,
                 reason: 'base_url_mismatch',
-                detail: `The skrr background service on this computer is not logged in to ${opts.baseURL}; it is logged in to ${mismatchedBootstrap.serverUrl}.`,
+                // What was READ, not a claim about the daemon: the descriptor may be
+                // another profile's (OSK-12117).
+                detail: `The daemon descriptor ${mismatchedPath ?? ''} is for ${mismatchedBootstrap.serverUrl}, not ${opts.baseURL}.`,
                 daemonServerUrl: mismatchedBootstrap.serverUrl,
+                ...(mismatchedPath ? { descriptorPath: mismatchedPath } : {}),
             };
         }
         return {
@@ -329,21 +392,164 @@ async function attemptDaemonBrokerLogin(opts) {
     // in". Only a refused connection falls through: any answer, or a timeout, is a
     // daemon that is really there, and its outcome stands.
     let outcome = null;
-    for (const bootstrap of usable) {
-        outcome = await brokerThrough(bootstrap, opts);
+    for (const { bootstrap, sourcePath } of usable) {
+        outcome = await brokerThrough(bootstrap, opts, sourcePath);
         if (outcome.ok || outcome.reason !== 'network')
             return outcome;
     }
     return outcome;
 }
-async function brokerThrough(bootstrap, opts) {
+async function brokerThrough(bootstrap, opts, sourcePath) {
+    // Mode negotiation (descriptor v2 `handoffModes`). A v1 descriptor advertises
+    // nothing and reads as `['refresh_family']` — today's behaviour, unchanged.
+    //
+    // The token route is attempted when the descriptor offers `access_token` AND
+    // either the caller prefers broker mode (auto-broker) or the durable mint is
+    // not offered at all (the Dedicated guest shape — its hand-off-only secret
+    // cannot mint a family, so the token route is the only door).
+    const modes = (0, cli_handoff_wire_1.advertisedHandoffModes)(bootstrap);
+    const offersAccessToken = modes.includes('access_token');
+    const offersRefreshFamily = modes.includes('refresh_family');
+    const preferAccessToken = opts.preferHandoffMode === 'access_token';
+    if (offersAccessToken && (preferAccessToken || !offersRefreshFamily)) {
+        const redeem = await redeemCliHandoffToken(bootstrap, {
+            forceRefresh: false,
+            timeoutMs: opts.timeoutMs,
+        });
+        if (redeem.ok) {
+            const response = redeem.body;
+            registerBrokeredHandoff(bootstrap, response.accessToken, sourcePath);
+            if (sourcePath === exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR) {
+                // A guest descriptor's secret can ONLY redeem access tokens, so a
+                // stored cli-auth.json on this machine predates broker mode. Retire
+                // the old family (best-effort revoke + delete); see the helper for
+                // the provenance guard.
+                await maybeRetireStoredCliAuthFile({
+                    descriptorPath: sourcePath,
+                    descriptorServerUrl: bootstrap.serverUrl ?? response.serverUrl,
+                });
+            }
+            return {
+                ok: true,
+                brokered: true,
+                accessToken: response.accessToken,
+                ...(response.accessExpiresAt !== undefined
+                    ? { accessExpiresAt: response.accessExpiresAt }
+                    : {}),
+                ...((response.serverUrl ?? bootstrap.serverUrl)
+                    ? { serverUrl: response.serverUrl ?? bootstrap.serverUrl }
+                    : {}),
+            };
+        }
+        // The descriptor ALSO advertises the durable mint (a laptop island during
+        // transition): any redeem failure — refusal, network, outage — falls
+        // through to the legacy route below. When refresh_family is NOT offered,
+        // the redeem outcome is final: the legacy route would only answer
+        // 403 HANDOFF_BROKER_ONLY anyway.
+        if (!offersRefreshFamily)
+            return redeem;
+    }
+    return mintRefreshFamilyThrough(bootstrap, opts);
+}
+/**
+ * Broker-mode redeem — `POST /v1/auth/cli-handoff-token` with the
+ * descriptor's secret as bearer. Returns the parsed token response or a
+ * `DaemonBrokerFailure` the caller can return verbatim / fall through from.
+ */
+async function redeemCliHandoffToken(bootstrap, opts = {}) {
+    const url = `http://${bootstrap.host}:${bootstrap.port}${cli_handoff_wire_1.CLI_HANDOFF_TOKEN_PATH}`;
+    const timeoutMs = opts.timeoutMs ?? REQUEST_TIMEOUT_MS;
+    const controller = new AbortController();
+    const abortTimer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        // The descriptor secret is a loopback-only credential: never `fetch`, which
+        // sends 127.0.0.1 to HTTP_PROXY under Bun and NODE_USE_ENV_PROXY (OSK-12134).
+        response = await (0, loopback_http_1.loopbackFetch)(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${bootstrap.secret}`,
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+            // No cliId — the family is daemon-owned; the caller is not enrolling a
+            // device. forceRefresh bypasses the daemon's cached access token (the
+            // 401-recovery path).
+            body: JSON.stringify({ forceRefresh: opts.forceRefresh === true }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (err.name === 'AbortError') {
+            return {
+                ok: false,
+                reason: 'timeout',
+                detail: `Handoff token redeem timed out after ${timeoutMs}ms`,
+            };
+        }
+        return { ok: false, reason: 'network', detail: msg };
+    }
+    finally {
+        clearTimeout(abortTimer);
+    }
+    let parsedBody = null;
+    try {
+        parsedBody = (await response.json());
+    }
+    catch {
+        parsedBody = null;
+    }
+    if (!response.ok) {
+        const code = typeof parsedBody?.code === 'string' ? parsedBody.code : undefined;
+        const message = typeof parsedBody?.message === 'string'
+            ? parsedBody.message
+            : `Handoff token route returned HTTP ${response.status}`;
+        if (response.status === 401 || response.status === 403) {
+            // The daemon refused the descriptor secret outright — the descriptor is
+            // stale (secret rotated on daemon restart) or was never valid for this
+            // route.
+            return {
+                ok: false,
+                reason: 'stale_bootstrap',
+                detail: message,
+                status: response.status,
+                ...(code ? { code } : {}),
+            };
+        }
+        return {
+            ok: false,
+            // 503 HANDOFF_TOKEN_UNAVAILABLE lands in server_error with its code
+            // preserved — the daemon is alive but cannot mint (no daemon bearer,
+            // upstream unreachable, mint cool-down). That is a daemon outage, not a
+            // decline, and the code keeps it diagnosable.
+            reason: response.status >= 500 ? 'server_error' : 'unknown',
+            detail: message,
+            status: response.status,
+            ...(code ? { code } : {}),
+        };
+    }
+    const body = (0, cli_handoff_wire_1.parseCliHandoffTokenResponse)(parsedBody);
+    if (!body) {
+        return {
+            ok: false,
+            reason: 'server_error',
+            detail: 'Handoff token route returned 200 but the response carried no access token',
+            status: response.status,
+        };
+    }
+    return { ok: true, body };
+}
+async function mintRefreshFamilyThrough(bootstrap, opts) {
     const url = `http://${bootstrap.host}:${bootstrap.port}/v1/auth/cli-handoff`;
     const timeoutMs = opts.timeoutMs ?? REQUEST_TIMEOUT_MS;
     const controller = new AbortController();
     const abortTimer = setTimeout(() => controller.abort(), timeoutMs);
     let response;
     try {
-        response = await fetch(url, {
+        // The descriptor secret is a loopback-only credential: never `fetch`, which
+        // sends 127.0.0.1 to HTTP_PROXY under Bun and NODE_USE_ENV_PROXY (OSK-12134).
+        response = await (0, loopback_http_1.loopbackFetch)(url, {
             method: 'POST',
             headers: {
                 Authorization: `Bearer ${bootstrap.secret}`,
@@ -389,6 +595,20 @@ async function brokerThrough(bootstrap, opts) {
         if (response.status === 403 && code === 'CI_TOKEN_REFUSED') {
             return { ok: false, reason: 'ci_token_refused', detail: message, status: 403, code };
         }
+        if (response.status === 403 && code === cli_handoff_wire_1.CLI_HANDOFF_ERROR_BROKER_ONLY) {
+            // The daemon refuses to mint a refresh family for this secret — the
+            // descriptor offers `access_token`, and broker mode is the only door.
+            // Terminal (not a next-candidate fall-through): every descriptor for
+            // this daemon answers the same way, and the caller's remedy is the
+            // token route or an explicit `skrr login`, not another file.
+            return {
+                ok: false,
+                reason: 'handoff_broker_only',
+                detail: message,
+                status: 403,
+                code,
+            };
+        }
         if (response.status === 503 && code === 'DAEMON_NOT_AUTHED') {
             return { ok: false, reason: 'daemon_not_authed', detail: message, status: 503, code };
         }
@@ -457,6 +677,116 @@ async function brokerThrough(bootstrap, opts) {
         ...(typeof parsedBody.familyId === 'string' ? { familyId: parsedBody.familyId } : {}),
     };
 }
+// ---------------------------------------------------------------------
+// Brokered (access-token) hand-off — process-local credential state
+// ---------------------------------------------------------------------
+/**
+ * The descriptor this process's brokered credential was redeemed from, and
+ * the token it answered. Module-scoped on purpose: broker mode persists
+ * NOTHING, so the only record of "the credential in use came from a hand-off
+ * redeem" lives here, for the 401 re-redeem path in `api-fetch`
+ * (`forceRefresh: true`, retry once). Each new `skrr` process starts empty
+ * and re-redeems on entry via `maybeAutoBroker`.
+ */
+let _brokeredHandoff = null;
+function registerBrokeredHandoff(descriptor, accessToken, sourcePath) {
+    _brokeredHandoff = { descriptor, accessToken, ...(sourcePath ? { sourcePath } : {}) };
+}
+/**
+ * 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).
+ */
+function isBrokeredHandoffToken(token) {
+    return Boolean(token && _brokeredHandoff && token === _brokeredHandoff.accessToken);
+}
+/**
+ * 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).
+ */
+async function redeemBrokeredHandoffToken(forceRefresh = true) {
+    const state = _brokeredHandoff;
+    if (!state)
+        return null;
+    const descriptor = (state.sourcePath ? readBootstrap(state.sourcePath) : null) ?? state.descriptor;
+    const result = await redeemCliHandoffToken(descriptor, { forceRefresh });
+    if (!result.ok)
+        return null;
+    _brokeredHandoff = { ...state, descriptor, accessToken: result.body.accessToken };
+    return result.body;
+}
+/** @internal test seam — clears the module-scoped brokered credential. */
+function __resetBrokeredHandoffForTest() {
+    _brokeredHandoff = null;
+}
+/**
+ * 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.
+ */
+function findBrokeredHandoffDescriptor(profile = 'default') {
+    for (const candidate of resolveCliHandoffCandidatePaths(profile)) {
+        const bootstrap = readBootstrap(candidate);
+        if (bootstrap && (0, cli_handoff_wire_1.descriptorOffersAccessToken)(bootstrap))
+            return bootstrap;
+    }
+    return 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.
+ */
+async function maybeRetireStoredCliAuthFile(opts) {
+    if (opts.descriptorPath !== exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR)
+        return;
+    let stored;
+    try {
+        stored = (0, auth_storage_1.readFromFile)();
+    }
+    catch {
+        return;
+    }
+    if (!stored?.refreshToken)
+        return;
+    const storedOrigin = stored.serverOrigin ? (0, auth_storage_1.normalizeServerOrigin)(stored.serverOrigin) : null;
+    const descriptorOrigin = opts.descriptorServerUrl
+        ? (0, auth_storage_1.normalizeServerOrigin)(opts.descriptorServerUrl)
+        : null;
+    if (!storedOrigin || !descriptorOrigin || storedOrigin !== descriptorOrigin)
+        return;
+    // The revoke is authenticated by the refresh token itself — presenting it
+    // is the proof of ownership. `revokeDaemonRefreshSession` swallows its own
+    // network/HTTP failures (best-effort by contract); the delete still runs.
+    try {
+        await (0, auth_core_1.revokeDaemonRefreshSession)(descriptorOrigin, stored.refreshToken);
+    }
+    catch {
+        /* best-effort — delete proceeds regardless */
+    }
+    (0, auth_storage_1.deleteFileBackend)();
+}
 /** Bound the confirm so a slow server cannot stall a login that already worked. */
 const CONFIRM_TIMEOUT_MS = 10_000;
 /**
@@ -514,15 +844,22 @@ function expiryToEpochMs(v) {
     return undefined;
 }
 /**
- * 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`.
+ * 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`.
  */
 async function attemptDaemonBrokerLoginAndPersist(opts) {
     const outcome = await attemptDaemonBrokerLogin(opts);
     if (!outcome.ok)
         return outcome;
+    // Brokered hand-off: a daemon-owned access token. The persistence policy
+    // IS the security property here — nothing credential-shaped lands on disk,
+    // so writeToBackend is never called and there is no family to confirm.
+    // Callers use the token in-memory for this process only.
+    if (outcome.brokered)
+        return outcome;
     const serverOrigin = normalizeBaseUrl(opts.baseURL);
     if (!serverOrigin) {
         throw new Error('Daemon-broker credential persistence requires a valid CLI baseURL.');
@@ -586,10 +923,12 @@ const AUTH_SELF_MANAGED_COMMANDS = new Set([
  *   - `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.
@@ -618,6 +957,12 @@ async function maybeAutoBroker(opts) {
     const outcome = await attemptDaemonBrokerLoginAndPersist({
         cliId,
         baseURL: opts.cliConfig.baseURL,
+        // Auto-broker prefers the brokered access-token mode when the descriptor
+        // advertises it: nothing credential-shaped is persisted, and the next
+        // `skrr` process simply re-redeems over loopback. The legacy refresh-
+        // family mint remains the fallback for v1 descriptors and the redeem
+        // path for explicit `skrr login`.
+        preferHandoffMode: 'access_token',
         ...(opts.bootstrapPathOverride ? { bootstrapPathOverride: opts.bootstrapPathOverride } : {}),
     });
     return {

package/dist/lib/dedicated-lease-command.d.ts

@@ -38,10 +38,24 @@ export declare abstract class DedicatedLeaseCommand extends BaseCommand {
      * machine, a daemon that is not connected, stdin that is not a terminal — so
      * the caller gets a sentence that says what to do instead of a start that
      * hangs and times out.
+     *
+     * Sessions are persistent by default (always-on §6.4): the daemon runs the
+     * shell inside tmux, so Ctrl-] and a lost connection only detach and the
+     * same command re-attaches the same shell. `--ephemeral` asks for the old
+     * bare-PTY semantics, and an image without `persistent_terminal_v1` gets
+     * them too — the relay forwards `persistent` as claimed and an old daemon
+     * silently ignores it, so the capability is checked here and the degraded
+     * start is announced rather than presented as resumable.
      */
     protected openDedicatedTerminal(leaseId: string, flags: {
         workspace?: string;
         cwd?: string;
+        /** Named session to attach-or-create (default 'main'); ignored with --new. */
+        name?: string;
+        /** A fresh session the machine names (term-N), printed once the ack reports it. */
+        new?: boolean;
+        /** The pre-persistent semantics: a bare PTY that ends with the connection. */
+        ephemeral?: boolean;
     }, initialCommand?: string): Promise<void>;
     /**
      * Run an API call, turning a refusal into the server's own sentence.

package/dist/lib/dedicated-lease-command.js

@@ -8,6 +8,7 @@ const base_command_1 = require("../base-command");
 const api_fetch_1 = require("./api-fetch");
 const dedicated_machines_1 = require("./dedicated-machines");
 const dedicated_terminal_1 = require("./dedicated-terminal");
+const dedicated_service_1 = require("./dedicated-service");
 const daemonBroker_1 = require("./daemonBroker");
 const harnesses_1 = require("./harnesses");
 const dedicated_wait_1 = require("./dedicated-wait");
@@ -72,6 +73,14 @@ class DedicatedLeaseCommand extends base_command_1.BaseCommand {
      * machine, a daemon that is not connected, stdin that is not a terminal — so
      * the caller gets a sentence that says what to do instead of a start that
      * hangs and times out.
+     *
+     * Sessions are persistent by default (always-on §6.4): the daemon runs the
+     * shell inside tmux, so Ctrl-] and a lost connection only detach and the
+     * same command re-attaches the same shell. `--ephemeral` asks for the old
+     * bare-PTY semantics, and an image without `persistent_terminal_v1` gets
+     * them too — the relay forwards `persistent` as claimed and an old daemon
+     * silently ignores it, so the capability is checked here and the degraded
+     * start is announced rather than presented as resumable.
      */
     async openDedicatedTerminal(leaseId, flags, initialCommand) {
         if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -92,7 +101,24 @@ class DedicatedLeaseCommand extends base_command_1.BaseCommand {
         if (!harness?.daemonId) {
             this.error(`${leaseId} is ${state}, but its daemon is not connected yet. Wait a moment, or run \`${this.config.bin} machines dedicated health-check ${leaseId}\`.`, { exit: 1 });
         }
-        process.stderr.write(`Connected to ${(0, dedicated_machines_1.dedicatedLeaseDisplayName)(lease)} (${leaseId}) as skrr-workload. Ctrl-] closes the terminal.\n`);
+        const capabilities = Array.isArray(harness.metadata?.capabilities)
+            ? harness.metadata.capabilities.filter((capability) => typeof capability === 'string')
+            : [];
+        const supportsPersistent = capabilities.includes(dedicated_service_1.DEDICATED_PERSISTENT_TERMINAL_CAPABILITY);
+        const persistent = flags.ephemeral !== true && supportsPersistent;
+        // `terminal` with no name means "the machine's terminal" — one stable
+        // session, attach-or-create, because a CLI has no picker to resume from.
+        // `--new` sends no name and the daemon allocates the next `term-N`, the
+        // same semantics the web picker's "New terminal" button has.
+        const sessionName = persistent && flags.new !== true ? (flags.name ?? 'main') : undefined;
+        if (flags.ephemeral !== true && !supportsPersistent) {
+            process.stderr.write(`${(0, dedicated_machines_1.dedicatedLeaseDisplayName)(lease)}'s image does not support persistent terminals ` +
+                `(${dedicated_service_1.DEDICATED_PERSISTENT_TERMINAL_CAPABILITY}), so this shell ends with the connection. ` +
+                `\`${this.config.bin} machines dedicated update-image ${leaseId}\` upgrades the machine.\n`);
+        }
+        process.stderr.write(persistent
+            ? `Connected to ${(0, dedicated_machines_1.dedicatedLeaseDisplayName)(lease)} (${leaseId}) as skrr-workload. Ctrl-] detaches; the session keeps running on the machine.\n`
+            : `Connected to ${(0, dedicated_machines_1.dedicatedLeaseDisplayName)(lease)} (${leaseId}) as skrr-workload. Ctrl-] closes the terminal.\n`);
         let code;
         try {
             code = await (0, dedicated_terminal_1.runDedicatedTerminal)({
@@ -102,6 +128,9 @@ class DedicatedLeaseCommand extends base_command_1.BaseCommand {
                 daemonId: harness.daemonId,
                 ...(flags.cwd ? { cwd: flags.cwd } : {}),
                 ...(initialCommand ? { initialCommand } : {}),
+                persistent,
+                ...(sessionName ? { sessionName } : {}),
+                leaseId,
                 input: process.stdin,
                 output: process.stdout,
                 errorOutput: process.stderr,