@skrr-ai/cli 0.1.49 → 0.1.51

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,
                 });

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

@@ -43,6 +43,31 @@ export declare const DEDICATED_SERVICE_EVENTS: {
     readonly logClosed: "dedicated:service:log:closed";
     readonly proposed: "dedicated:service:proposed";
 };
+/**
+ * Persistent-terminal management (always-on §6.4) — the sibling lane on the
+ * same admitted socket. A session is a tmux `skrr-term-<name>` the machine
+ * keeps alive across attaches; `terminal` opens one over the ordinary
+ * terminal start lane, and these verbs enumerate, end and rename it.
+ */
+export declare const DEDICATED_TERMINAL_EVENTS: {
+    readonly list: "dedicated:terminal:list";
+    readonly kill: "dedicated:terminal:kill";
+    readonly rename: "dedicated:terminal:rename";
+    readonly ack: "dedicated:terminal:ack";
+};
+export type TerminalVerb = 'list' | 'kill' | 'rename';
+/** `skrr-term-<name>`'s suffix — the pattern the relay and daemon both enforce. */
+export declare const DEDICATED_TERMINAL_NAME_PATTERN: RegExp;
+/** The wire capability a live daemon must announce for persistent terminals. */
+export declare const DEDICATED_PERSISTENT_TERMINAL_CAPABILITY = "persistent_terminal_v1";
+/** One `dedicated:terminal:list` row — the tmux session under its suffix. */
+export interface DedicatedTerminalSessionInfo {
+    name: string;
+    /** tmux `session_created` — SECONDS when numeric, not milliseconds. */
+    createdAt?: string | number;
+    attached?: boolean;
+    windows?: number;
+}
 /** How long a verb has to answer before the machine is declared unreachable. */
 export declare const SERVICE_CALL_TIMEOUT_MS = 30000;
 /** §5.3 — the scope name `skrr-svc-<name>` derives from it. */
@@ -167,6 +192,17 @@ export declare function describeServiceRefusal(ack: Pick<DedicatedServiceAck, 'c
     verb?: string;
     name?: string;
 }): string;
+/**
+ * A persistent-terminal refusal in the same register `describeServiceRefusal`
+ * gives the service lane — a named condition and the next step, never a bare
+ * code. `dedicated:terminal:*` acks share this channel's requestId shape, so
+ * the same refusal codes arrive; the words name terminal sessions, not specs.
+ */
+export declare function describeTerminalRefusal(ack: Pick<DedicatedServiceAck, 'code' | 'error'>, context?: {
+    leaseId?: string;
+    verb?: string;
+    name?: string;
+}): string;
 /** Validation that costs the daemon nothing to re-check — §5.3's table, enforced client-side first. */
 export declare function validateServiceSpec(doc: unknown, options?: {
     requireName?: boolean;
@@ -251,6 +287,16 @@ export declare class DedicatedServiceChannel {
         result: T | undefined;
         ack: DedicatedServiceAck;
     }>;
+    /**
+     * A persistent-terminal verb — `dedicated:terminal:list|kill|rename`,
+     * answered on `dedicated:terminal:ack`. Same requestId/ack discipline as
+     * the service verbs; the event family and the refusal's wording are the
+     * only differences.
+     */
+    callTerminal<T = unknown>(verb: TerminalVerb, payload: Record<string, unknown>, timeoutMs?: number): Promise<{
+        result: T | undefined;
+        ack: DedicatedServiceAck;
+    }>;
     /** The shared request/ack round-trip. */
     private callEvent;
     /** Subscribe to a server-pushed frame (`state`, `log`, `log:closed`, `proposed`). */

package/dist/lib/dedicated-service.js

@@ -3,9 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GUEST_SERVICE_SOCKET_PATH = exports.DedicatedServiceChannel = exports.DedicatedServiceError = exports.SERVICE_ACTIONS = exports.SERVICE_RESTART_POLICIES = exports.SERVICE_RESERVED_NAMES = exports.SERVICE_SECRET_NAME_PATTERN = exports.SERVICE_NAME_PATTERN = exports.SERVICE_CALL_TIMEOUT_MS = exports.DEDICATED_SERVICE_EVENTS = void 0;
+exports.GUEST_SERVICE_SOCKET_PATH = exports.DedicatedServiceChannel = exports.DedicatedServiceError = exports.SERVICE_ACTIONS = exports.SERVICE_RESTART_POLICIES = exports.SERVICE_RESERVED_NAMES = exports.SERVICE_SECRET_NAME_PATTERN = exports.SERVICE_NAME_PATTERN = exports.SERVICE_CALL_TIMEOUT_MS = exports.DEDICATED_PERSISTENT_TERMINAL_CAPABILITY = exports.DEDICATED_TERMINAL_NAME_PATTERN = exports.DEDICATED_TERMINAL_EVENTS = exports.DEDICATED_SERVICE_EVENTS = void 0;
 exports.isServiceUnsupportedCode = isServiceUnsupportedCode;
 exports.describeServiceRefusal = describeServiceRefusal;
+exports.describeTerminalRefusal = describeTerminalRefusal;
 exports.validateServiceSpec = validateServiceSpec;
 exports.parseServiceSpecDocument = parseServiceSpecDocument;
 exports.specPayload = specPayload;
@@ -72,6 +73,22 @@ exports.DEDICATED_SERVICE_EVENTS = {
     logClosed: 'dedicated:service:log:closed',
     proposed: 'dedicated:service:proposed',
 };
+/**
+ * Persistent-terminal management (always-on §6.4) — the sibling lane on the
+ * same admitted socket. A session is a tmux `skrr-term-<name>` the machine
+ * keeps alive across attaches; `terminal` opens one over the ordinary
+ * terminal start lane, and these verbs enumerate, end and rename it.
+ */
+exports.DEDICATED_TERMINAL_EVENTS = {
+    list: 'dedicated:terminal:list',
+    kill: 'dedicated:terminal:kill',
+    rename: 'dedicated:terminal:rename',
+    ack: 'dedicated:terminal:ack',
+};
+/** `skrr-term-<name>`'s suffix — the pattern the relay and daemon both enforce. */
+exports.DEDICATED_TERMINAL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/** The wire capability a live daemon must announce for persistent terminals. */
+exports.DEDICATED_PERSISTENT_TERMINAL_CAPABILITY = 'persistent_terminal_v1';
 /** How long a verb has to answer before the machine is declared unreachable. */
 exports.SERVICE_CALL_TIMEOUT_MS = 30_000;
 /** §5.3 — the scope name `skrr-svc-<name>` derives from it. */
@@ -106,6 +123,7 @@ exports.DedicatedServiceError = DedicatedServiceError;
 function isServiceUnsupportedCode(code) {
     const c = (code || '').toLowerCase();
     return (c === 'dedicated_runtime_services_unsupported' ||
+        c === 'dedicated_runtime_terminal_unsupported' ||
         c === 'services_unsupported' ||
         c === 'unsupported' ||
         c === 'not_implemented' ||
@@ -152,6 +170,48 @@ function describeServiceRefusal(ack, context = {}) {
     }
     return ack.error ? `The service request failed: ${ack.error}` : 'The service request failed.';
 }
+/**
+ * A persistent-terminal refusal in the same register `describeServiceRefusal`
+ * gives the service lane — a named condition and the next step, never a bare
+ * code. `dedicated:terminal:*` acks share this channel's requestId shape, so
+ * the same refusal codes arrive; the words name terminal sessions, not specs.
+ */
+function describeTerminalRefusal(ack, context = {}) {
+    const code = ack.code || '';
+    if (isServiceUnsupportedCode(code)) {
+        return (ack.error ||
+            `This machine's image does not support persistent terminals (persistent_terminal_v1). ` +
+                `Update it with \`skrr machines dedicated update-image ${context.leaseId || '<lease-id>'} --wait\`; \`skrr machines dedicated terminal\` opens a plain shell in the meantime.`);
+    }
+    if (code === 'DEDICATED_RUNTIME_NOT_ASSIGNABLE') {
+        return ('The machine is not ready to take terminal commands (it must be running with a healthy workspace). ' +
+            `Check it with \`skrr machines dedicated show ${context.leaseId || '<lease-id>'}\`.`);
+    }
+    if (code === 'DEDICATED_RUNTIME_GENERATION_STALE') {
+        return 'The machine was replaced since its daemon registered. Wait a minute and try again.';
+    }
+    if (code === 'dedicated_runtime_quiesced') {
+        return 'The machine is checkpointing its workspace right now; try again in a moment.';
+    }
+    if (code === 'offline' ||
+        code === 'daemon_offline' ||
+        code === 'daemon-gone' ||
+        code === 'daemon-timeout') {
+        return 'The machine’s daemon is not answering. Wait for it to come online and try again.';
+    }
+    if (code === 'not_found') {
+        return context.name
+            ? `No terminal session named ${context.name} on this machine — \`skrr machines dedicated terminal ls ${context.leaseId || '<lease-id>'}\` lists them.`
+            : 'The machine or the named session was not found.';
+    }
+    if (code === 'invalid' || code === 'validation') {
+        return `The terminal request was refused: ${ack.error || 'invalid request'}`;
+    }
+    if (code === 'rate-limited' || code === 'cap') {
+        return 'Too many terminal requests in flight — wait a moment and retry.';
+    }
+    return ack.error ? `The terminal request failed: ${ack.error}` : 'The terminal request failed.';
+}
 /* ---------------------------------------------------------------- spec --- */
 /** Validation that costs the daemon nothing to re-check — §5.3's table, enforced client-side first. */
 function validateServiceSpec(doc, options = {}) {
@@ -383,18 +443,22 @@ class DedicatedServiceChannel {
         this.options = options;
         const connect = options.connect ?? socket_io_client_1.io;
         this.socket = connect((0, agentic_stream_1.toWebSocketOrigin)(options.baseURL), socketOptions(options.token));
-        const onAck = (ack) => {
+        // An ack resolves a request only when it arrives on THAT request's own
+        // ack event — a requestId echoed back on the wrong family is not an
+        // answer, however well-formed it looks.
+        const onAck = (ackEvent) => (ack) => {
             if (!ack?.requestId)
                 return;
             const waiter = this.pending.get(ack.requestId);
-            if (!waiter)
+            if (!waiter || waiter.ackEvent !== ackEvent)
                 return;
             this.pending.delete(ack.requestId);
             clearTimeout(waiter.timer);
             waiter.resolve(ack);
         };
-        this.socket.on(exports.DEDICATED_SERVICE_EVENTS.ack, onAck);
-        this.socket.on(exports.DEDICATED_SERVICE_EVENTS.templatesAck, onAck);
+        this.socket.on(exports.DEDICATED_SERVICE_EVENTS.ack, onAck(exports.DEDICATED_SERVICE_EVENTS.ack));
+        this.socket.on(exports.DEDICATED_SERVICE_EVENTS.templatesAck, onAck(exports.DEDICATED_SERVICE_EVENTS.templatesAck));
+        this.socket.on(exports.DEDICATED_TERMINAL_EVENTS.ack, onAck(exports.DEDICATED_TERMINAL_EVENTS.ack));
     }
     /** Resolves once the transport is up; rejects on connect failure. */
     open() {
@@ -455,8 +519,21 @@ class DedicatedServiceChannel {
             verb: `templates:${verb}`,
         }, timeoutMs);
     }
+    /**
+     * A persistent-terminal verb — `dedicated:terminal:list|kill|rename`,
+     * answered on `dedicated:terminal:ack`. Same requestId/ack discipline as
+     * the service verbs; the event family and the refusal's wording are the
+     * only differences.
+     */
+    callTerminal(verb, payload, timeoutMs = exports.SERVICE_CALL_TIMEOUT_MS) {
+        return this.callEvent(`dedicated:terminal:${verb}`, exports.DEDICATED_TERMINAL_EVENTS.ack, payload, {
+            leaseId: typeof payload.leaseId === 'string' ? payload.leaseId : undefined,
+            verb: `terminal:${verb}`,
+            name: typeof payload.name === 'string' ? payload.name : undefined,
+        }, timeoutMs, describeTerminalRefusal);
+    }
     /** The shared request/ack round-trip. */
-    callEvent(event, ackEvent, payload, context, timeoutMs) {
+    callEvent(event, ackEvent, payload, context, timeoutMs, describe = describeServiceRefusal) {
         const requestId = `svc-${(0, node_crypto_1.randomUUID)()}`;
         return new Promise((resolve, reject) => {
             if (this.dead) {
@@ -469,9 +546,10 @@ class DedicatedServiceChannel {
             }, timeoutMs);
             this.pending.set(requestId, {
                 timer,
+                ackEvent,
                 resolve: (ack) => {
                     if (!ack.ok) {
-                        reject(new DedicatedServiceError(describeServiceRefusal(ack, context), ack.code || 'SERVICE_REFUSED'));
+                        reject(new DedicatedServiceError(describe(ack, context), ack.code || 'SERVICE_REFUSED'));
                         return;
                     }
                     resolve({ result: ack.result, ack });

package/dist/lib/dedicated-terminal.d.ts

@@ -34,6 +34,8 @@ export interface TerminalStartAck {
     ok?: boolean;
     error?: string;
     code?: string;
+    /** The tmux session a persistent start attached (`skrr-term-<name>`'s suffix). */
+    persistentName?: string;
 }
 /** Bytes of one output frame, without splitting a UTF-8 or ANSI sequence. */
 export declare function decodeTerminalFrame(frame: TerminalOutputFrame): Buffer;
@@ -56,6 +58,25 @@ export interface DedicatedTerminalOptions {
     daemonId: string;
     cwd?: string;
     initialCommand?: string;
+    /**
+     * A tmux-backed session (always-on §6.4): the machine keeps it alive across
+     * attaches, disconnects and daemon restarts, and a reconnect re-attaches it
+     * by name instead of opening a new shell. A daemon that predates
+     * `persistent_terminal_v1` silently ignores it — callers gate on the
+     * capability before asking.
+     */
+    persistent?: boolean;
+    /**
+     * The session suffix (`skrr-term-<name>`). The same name re-attaches the
+     * same session; omitted under `persistent`, the machine names the session
+     * `term-N` and the start ack reports it as `persistentName`.
+     */
+    sessionName?: string;
+    /**
+     * The lease this terminal claims — the relay refuses a start that names a
+     * lease but resolves to another lease's daemon.
+     */
+    leaseId?: string;
     input: NodeJS.ReadStream;
     output: NodeJS.WriteStream;
     errorOutput: NodeJS.WritableStream;

package/dist/lib/dedicated-terminal.js

@@ -78,13 +78,22 @@ function describeTerminalStartRefusal(ack) {
  */
 function runDedicatedTerminal(options) {
     const events = data_provider_1.HARNESS_TERMINAL_EVENTS;
-    const sessionId = (0, node_crypto_1.randomUUID)();
+    const persistent = options.persistent === true;
     const connect = options.connect ?? socket_io_client_1.io;
     const { input, output, errorOutput } = options;
     return new Promise((resolve, reject) => {
+        // The daemon keys a terminal by the sessionId in its start — one attach.
+        // A persistent session re-attaches across socket reconnects, and each
+        // attach is a fresh id over the same tmux name.
+        let sessionId = '';
         let started = false;
         let finished = false;
         let rawMode = false;
+        // First attach armed the tty; a re-attach needs only the ack, not the
+        // setup again.
+        let sessionReady = false;
+        let reattaching = false;
+        let persistentName = options.sessionName;
         const socket = connect((0, agentic_stream_1.toWebSocketOrigin)(options.baseURL), {
             path: '/ws/agentic',
             auth: {
@@ -94,10 +103,15 @@ function runDedicatedTerminal(options) {
                 clientOs: process.platform === 'darwin' ? 'macos' : process.platform,
             },
             transports: ['websocket'],
-            // A reconnect cannot resume a PTY: the relay forgets the session with the
+            // A bare PTY cannot be resumed: the relay forgets the session with the
             // socket, and silently opening a NEW shell would drop the user into a
-            // different process tree mid-command. Say it ended instead.
-            reconnection: false,
+            // different process tree mid-command — say it ended instead. A
+            // persistent session is the opposite by design: tmux keeps it, and the
+            // reconnect re-attaches it BY NAME, which is the same shell.
+            reconnection: persistent,
+            reconnectionAttempts: 10,
+            reconnectionDelay: 1_000,
+            reconnectionDelayMax: 5_000,
         });
         // Typed only once the shell's line editor says it is reading a command line
         // (`createPendingShellCommand`, the rule the web terminal reads too). A
@@ -106,7 +120,10 @@ function runDedicatedTerminal(options) {
         const pending = initialCommand
             ? (0, data_provider_1.createPendingShellCommand)({
                 command: initialCommand,
-                send: (data) => socket.emit(events.input, { sessionId, data }),
+                send: (data) => {
+                    if (started)
+                        socket.emit(events.input, { sessionId, data });
+                },
                 onStatusChange: (status) => {
                     const notice = describePendingCommand(status, initialCommand);
                     if (notice && !finished)
@@ -129,13 +146,20 @@ function runDedicatedTerminal(options) {
                 if (detachAt > 0) {
                     const typed = buffer.subarray(0, detachAt);
                     pending?.observeUserInput(typed);
-                    socket.emit(events.input, { sessionId, data: typed.toString('utf8') });
+                    if (started)
+                        socket.emit(events.input, { sessionId, data: typed.toString('utf8') });
                 }
-                errorOutput.write('\r\n[closed the terminal]\r\n');
+                errorOutput.write(persistent && persistentName
+                    ? `\r\n[detached — session '${persistentName}' keeps running on the machine]\r\n`
+                    : '\r\n[closed the terminal]\r\n');
                 finish(0, true);
                 return;
             }
             pending?.observeUserInput(buffer);
+            // While a reconnect is in flight the attach is gone: the frame would be
+            // dropped daemon-side anyway, so it is not sent.
+            if (!started)
+                return;
             socket.emit(events.input, { sessionId, data: buffer.toString('utf8') });
         };
         // A terminal that closes (SIGHUP) or a supervisor that stops us (SIGTERM):
@@ -145,9 +169,11 @@ function runDedicatedTerminal(options) {
         // SIGINT's status, for both.
         const onSigterm = () => finish(143, true);
         const onSighup = () => finish(129, true);
-        const startTimer = setTimeout(() => {
+        const onStartTimeout = () => {
             fail(new DedicatedTerminalError('The machine did not answer the terminal start in time. Its daemon may be busy or offline.', 'TERMINAL_START_TIMEOUT'));
-        }, exports.TERMINAL_START_TIMEOUT_MS);
+        };
+        let startTimer = setTimeout(onStartTimeout, exports.TERMINAL_START_TIMEOUT_MS);
+        startTimer.unref();
         function restoreTty() {
             input.off('data', onInput);
             output.off('resize', onResize);
@@ -166,6 +192,7 @@ function runDedicatedTerminal(options) {
             clearTimeout(startTimer);
             pending?.close();
             restoreTty();
+            detachReconnectFailed();
             if (stopRemote && started)
                 socket.emit(events.stop, { sessionId });
             socket.disconnect();
@@ -178,17 +205,34 @@ function runDedicatedTerminal(options) {
             clearTimeout(startTimer);
             pending?.close();
             restoreTty();
+            detachReconnectFailed();
             socket.disconnect();
             reject(error);
         }
         socket.on('connect_error', (err) => {
+            // A failed retry while reattaching is not fatal — the attempt countdown
+            // keeps running and `reconnect_failed` ends it if they all miss.
+            if (persistent && reattaching)
+                return;
             fail(new DedicatedTerminalError(`Could not connect to skrr: ${err.message}`, err.data?.code || 'TERMINAL_CONNECT_FAILED'));
         });
         socket.on('connect', () => {
+            if (finished)
+                return;
+            sessionId = (0, node_crypto_1.randomUUID)();
+            clearTimeout(startTimer);
+            startTimer = setTimeout(onStartTimeout, exports.TERMINAL_START_TIMEOUT_MS);
+            startTimer.unref();
             socket.emit(events.start, {
                 runtimeId: options.runtimeId,
                 sessionId,
                 ...(options.cwd ? { cwd: options.cwd } : {}),
+                ...(persistent ? { persistent: true } : {}),
+                // The RESOLVED name, not just the requested one: a `--new` session the
+                // machine named itself comes back in the ack, and a re-attach must
+                // name it — `tmux -A` without `-s` would open a fresh session instead.
+                ...(persistentName ? { sessionName: persistentName } : {}),
+                ...(options.leaseId ? { leaseId: options.leaseId } : {}),
                 ...size(),
             });
         });
@@ -201,8 +245,20 @@ function runDedicatedTerminal(options) {
                 fail(new DedicatedTerminalError(describeTerminalStartRefusal(ack), ack.code || 'TERMINAL_START_REFUSED'));
                 return;
             }
+            const reattached = reattaching;
             started = true;
+            reattaching = false;
             clearTimeout(startTimer);
+            if (typeof ack.persistentName === 'string' && ack.persistentName) {
+                persistentName = ack.persistentName;
+            }
+            if (sessionReady) {
+                if (reattached) {
+                    errorOutput.write(`\r\n[reattached to session '${persistentName}']\r\n`);
+                }
+                return;
+            }
+            sessionReady = true;
             if (typeof input.setRawMode === 'function') {
                 input.setRawMode(true);
                 rawMode = true;
@@ -213,6 +269,9 @@ function runDedicatedTerminal(options) {
             process.on('SIGTERM', onSigterm);
             process.on('SIGHUP', onSighup);
             pending?.beginSession();
+            if (persistent && persistentName) {
+                errorOutput.write(`\r\n[session '${persistentName}' is kept alive on the machine — Ctrl-] detaches, the same command re-attaches]\r\n`);
+            }
         });
         socket.on(events.output, (frame) => {
             if (!frame || frame.sessionId !== sessionId || finished)
@@ -233,9 +292,45 @@ function runDedicatedTerminal(options) {
             output.write(bytes);
             pending?.observeOutput(bytes);
         });
+        // socket.io reports a given-up reconnect on the manager; a bare EventEmitter
+        // test socket has none, so the socket itself carries the listener then.
+        const onReconnectFailed = () => {
+            if (finished || !persistent)
+                return;
+            const named = persistentName ? ` '${persistentName}'` : '';
+            errorOutput.write(`\r\n[could not reconnect to skrr — session${named} still runs on the machine; rerun the same command to reattach]\r\n`);
+            finish(1, false);
+        };
+        const manager = socket.io;
+        const onManager = typeof manager?.on === 'function';
+        if (onManager)
+            manager.on('reconnect_failed', onReconnectFailed);
+        else
+            socket.on('reconnect_failed', onReconnectFailed);
+        // The manager is SHARED per url+path (socket.io multiplexing), so the
+        // listener outlives this terminal unless it is removed on every exit.
+        function detachReconnectFailed() {
+            if (onManager && typeof manager?.off === 'function') {
+                manager.off('reconnect_failed', onReconnectFailed);
+            }
+            else if (!onManager) {
+                socket.off('reconnect_failed', onReconnectFailed);
+            }
+        }
         socket.on('disconnect', () => {
             if (finished)
                 return;
+            if (persistent) {
+                // The tmux session outlives the link — the tmux client's death only
+                // detaches. socket.io retries and the next start re-attaches by name.
+                started = false;
+                if (!reattaching) {
+                    reattaching = true;
+                    const named = persistentName ? ` '${persistentName}'` : '';
+                    errorOutput.write(`\r\n[lost the connection to skrr — reattaching to session${named}…]\r\n`);
+                }
+                return;
+            }
             if (!started) {
                 fail(new DedicatedTerminalError('The connection to skrr closed before the terminal started.', 'TERMINAL_DISCONNECTED'));
                 return;

package/dist/lib/delegated-cli.js

@@ -49,6 +49,7 @@ const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const auth_core_1 = require("@skrr-ai/auth-core");
+const loopback_http_1 = require("@skrr-ai/auth-core/loopback-http");
 function isDelegatedCliSession(env = process.env) {
     return Boolean(env.OVERSKY_AUTONOMOUS_SESSION === '1' &&
         env.OVERSKY_DELEGATED_CLI_BROKER_URL?.trim() &&
@@ -213,7 +214,9 @@ async function fetchDelegatedCliCredential(env = process.env, options = {}) {
     try {
         let res;
         try {
-            res = await fetch(brokerUrl, {
+            // Proxy-free and loopback-only (OSK-12134): the capability and the
+            // credential it returns must never reach HTTP_PROXY.
+            res = await (0, loopback_http_1.loopbackFetch)(brokerUrl, {
                 method: 'POST',
                 headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
                 body: JSON.stringify({

package/dist/lib/exec-runtime-binary.d.ts

@@ -71,7 +71,9 @@ export declare function notInstalledMessage(): string;
  * preserving "exit code = the daemon's exit code" semantics that scripts
  * may depend on.
  */
-export declare function execRuntimeBinary(args: string[]): Promise<number>;
+export declare function execRuntimeBinary(args: string[], opts?: {
+    binary?: string;
+}): Promise<number>;
 /** Output from a short-lived runtime probe such as `skrrd status --json`. */
 export type RuntimeBinaryOutput = {
     code: number;

package/dist/lib/exec-runtime-binary.js

@@ -212,9 +212,11 @@ function notInstalledMessage() {
  * preserving "exit code = the daemon's exit code" semantics that scripts
  * may depend on.
  */
-function execRuntimeBinary(args) {
+function execRuntimeBinary(args, opts = {}) {
     return new Promise((resolve, reject) => {
-        const bin = findRuntimeBinary();
+        // `binary` lets `status` render from the LIVE daemon's program rather than
+        // the first one on PATH (OSK-12102); every other verb forwards to PATH.
+        const bin = opts.binary ?? findRuntimeBinary();
         if (!bin) {
             reject(new Error('runtime-binary-not-installed'));
             return;

package/dist/lib/first-party-harness-broker.d.ts

@@ -223,6 +223,16 @@ export interface ManagedEngineHooks {
      * never from the env this hook returned.
      */
     credentialMode: () => 'managed' | 'byok';
+    /**
+     * `prepare` fell back to BYOK AND no provider credential will reach the
+     * engine — the exact case where the fallback line already warned that the
+     * first request will fail. The caller uses this AFTER a non-zero engine
+     * exit to tie an opaque engine failure (an `Unexpected server error` that
+     * says nothing about auth) back to the missing credential, without
+     * refusing the launch up front: the engine can carry a stored credential
+     * `hasProviderCredential` cannot see (OSK-11949).
+     */
+    unprovisionedByok: () => boolean;
 }
 export interface ManagedEngineHooksInput {
     subcommand: string | null;