@skrr-ai/cli 0.1.48 → 0.1.50

package/dist/lib/daemonBroker.js

@@ -80,11 +80,18 @@ exports.resolveCliHandoffCandidatePaths = resolveCliHandoffCandidatePaths;
 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 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");
@@ -233,19 +240,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,6 +296,8 @@ 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;
@@ -300,10 +315,10 @@ async function attemptDaemonBrokerLogin(opts) {
         }
         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) {
@@ -329,14 +344,153 @@ 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 {
+        response = await fetch(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();
@@ -389,6 +543,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 +625,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 +792,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 +871,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 +905,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,

package/dist/lib/dedicated-machines.js

@@ -50,6 +50,7 @@ exports.formatDedicatedRuntimeApiError = formatDedicatedRuntimeApiError;
 const auth_core_1 = require("@skrr-ai/auth-core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const api_fetch_1 = require("./api-fetch");
+const machine_spend_cap_1 = require("./machine-spend-cap");
 const edge_error_page_1 = require("./edge-error-page");
 const harnesses_1 = require("./harnesses");
 exports.DEDICATED_LEASE_ACTIONS = [
@@ -1185,7 +1186,7 @@ function dedicatedRuntimeApiErrorDetails(err) {
  */
 function describeRefusalReasons(err, context = {}) {
     const details = dedicatedRuntimeApiErrorDetails(err);
-    const spend = describeSpendingCapRefusal(err.body, details, context);
+    const spend = describeSpendingCapRefusal(err.body, context);
     if (spend)
         return spend;
     const sentences = (0, harnesses_1.describeHealthReasonSentences)(details?.reasons, details?.state);
@@ -1197,31 +1198,13 @@ function describeRefusalReasons(err, context = {}) {
  * the cap. Without them "would exceed the monthly cap" left a user guessing by
  * how much, and which cap (OSK-9552).
  */
-function describeSpendingCapRefusal(body, details, context = {}) {
-    let code;
-    try {
-        code = JSON.parse(body || '{}').code;
-    }
-    catch {
-        return '';
-    }
-    if (code !== 'RUNTIME_SPENDING_LIMIT_EXCEEDED' || !details)
-        return '';
-    const cents = (key) => {
-        const value = details[key];
-        return typeof value === 'number' && Number.isFinite(value) ? value : null;
-    };
-    const limit = cents('limitCents');
-    const spent = cents('currentSpendCents');
-    const projected = cents('projectedCents');
-    const parts = [
-        limit !== null ? `Cap ${formatUsdCents(limit)}` : '',
-        spent !== null ? `spent this month ${formatUsdCents(spent)}` : '',
-        projected !== null ? `this would bring it to ${formatUsdCents(projected)}` : '',
-    ].filter(Boolean);
-    if (parts.length === 0)
+function describeSpendingCapRefusal(body, context = {}) {
+    // Shared with the hosted CLI (machine-spend-cap.ts), which printed the bare
+    // sentence until OSK-11946.
+    const figures = (0, machine_spend_cap_1.describeMonthlyCapFigures)(body);
+    if (!figures)
         return '';
-    return ` ${parts.join('; ')}. ${raiseCapHint(context)}`;
+    return ` ${figures}. ${raiseCapHint(context)}`;
 }
 /**
  * How to get past a cap refusal, for the command that was refused. A create or

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

@@ -1,5 +1,5 @@
 import { DedicatedLeaseCommand } from './dedicated-lease-command';
-import { DedicatedServiceChannel, type ServiceVerb } from './dedicated-service';
+import { DedicatedServiceChannel, type ServiceVerb, type TerminalVerb } from './dedicated-service';
 /**
  * The flag set `service create`/`apply` and guest `service propose` share —
  * one definition so the three surfaces cannot drift apart on what a spec
@@ -40,6 +40,12 @@ export declare abstract class DedicatedServiceCommand extends DedicatedLeaseComm
     protected serviceChannel(): Promise<DedicatedServiceChannel>;
     /** Emit one verb and return the daemon's `result`, or throw as a CLI error. */
     protected callService<T = unknown>(verb: ServiceVerb, payload: Record<string, unknown>, timeoutMs?: number): Promise<T | undefined>;
+    /**
+     * Emit one persistent-terminal verb (`dedicated:terminal:list|kill|rename`)
+     * on the same admitted channel the service verbs ride — the relay answers
+     * `dedicated:terminal:ack` with the same requestId discipline.
+     */
+    protected callDedicatedTerminal<T = unknown>(verb: TerminalVerb, payload: Record<string, unknown>, timeoutMs?: number): Promise<T | undefined>;
     /**
      * `start|stop|restart|rm` — the shared `dedicated:service:action` round
      * trip and its printout. `rm` maps to the `remove` action on the wire (the
@@ -54,7 +60,9 @@ export declare abstract class DedicatedServiceCommand extends DedicatedLeaseComm
     /**
      * Turn a service-lane failure into the command's exit — the refusal
      * sentence the relay sent, or the clean capability-missing path the SSH
-     * lane established for a missing `sshBridge`.
+     * lane established for a missing `sshBridge`. `unsupportedCode` is the
+     * lane's own code a `--json` error reports; the terminal lane passes its
+     * own so a script can tell "no persistent terminals" from "no services".
      */
-    protected reportServiceError(err: unknown): never;
+    protected reportServiceError(err: unknown, unsupportedCode?: string): never;
 }

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

@@ -94,6 +94,21 @@ class DedicatedServiceCommand extends dedicated_lease_command_1.DedicatedLeaseCo
             this.reportServiceError(err);
         }
     }
+    /**
+     * Emit one persistent-terminal verb (`dedicated:terminal:list|kill|rename`)
+     * on the same admitted channel the service verbs ride — the relay answers
+     * `dedicated:terminal:ack` with the same requestId discipline.
+     */
+    async callDedicatedTerminal(verb, payload, timeoutMs) {
+        try {
+            const channel = await this.serviceChannel();
+            const { result } = await channel.callTerminal(verb, payload, timeoutMs);
+            return result;
+        }
+        catch (err) {
+            this.reportServiceError(err, 'DEDICATED_RUNTIME_TERMINAL_UNSUPPORTED');
+        }
+    }
     /**
      * `start|stop|restart|rm` — the shared `dedicated:service:action` round
      * trip and its printout. `rm` maps to the `remove` action on the wire (the
@@ -143,14 +158,16 @@ class DedicatedServiceCommand extends dedicated_lease_command_1.DedicatedLeaseCo
     /**
      * Turn a service-lane failure into the command's exit — the refusal
      * sentence the relay sent, or the clean capability-missing path the SSH
-     * lane established for a missing `sshBridge`.
+     * lane established for a missing `sshBridge`. `unsupportedCode` is the
+     * lane's own code a `--json` error reports; the terminal lane passes its
+     * own so a script can tell "no persistent terminals" from "no services".
      */
-    reportServiceError(err) {
+    reportServiceError(err, unsupportedCode = 'DEDICATED_RUNTIME_SERVICES_UNSUPPORTED') {
         if (err instanceof dedicated_service_1.DedicatedServiceError) {
             if ((0, dedicated_service_1.isServiceUnsupportedCode)(err.code)) {
                 this.failWithCliError({
                     message: err.message,
-                    code: 'DEDICATED_RUNTIME_SERVICES_UNSUPPORTED',
+                    code: unsupportedCode,
                     exit: 1,
                     retryable: false,
                 });