@skrr-ai/cli 0.1.80 → 0.1.81

package/dist/lib/dedicated-ssh.js

@@ -23,6 +23,7 @@ const socket_io_client_1 = require("socket.io-client");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const agentic_stream_1 = require("./agentic-stream");
 const dpop_auth_1 = require("./dpop-auth");
+const ssh_ordered_bytes_1 = require("./ssh-ordered-bytes");
 /**
  * Owner SSH to a Dedicated Runtime — SSH protocol over the admitted relay.
  *
@@ -278,48 +279,103 @@ function describeSshStartRefusal(ack) {
  */
 function runSshProxy(options) {
     const channelId = `ssh-${(0, node_crypto_1.randomUUID)()}`;
+    const resumeProof = (0, node_crypto_1.randomBytes)(32).toString('hex');
     const connect = options.connect ?? socket_io_client_1.io;
     const { input, output, errorOutput } = options;
     const identity = ensureSshIdentity();
     const writeHosts = options.writeKnownHosts ?? writeKnownHosts;
+    const recoveryMs = options.recoveryMs ?? 45_000;
+    const receiver = new ssh_ordered_bytes_1.SshOrderedBytes();
     return new Promise((resolve) => {
         let started = false;
+        let startSent = false;
         let finished = false;
+        let online = false;
+        let attached = false;
+        let resumable = false;
+        let generation = null;
+        let epoch = (0, node_crypto_1.randomUUID)();
+        let recoveringSince = null;
+        let inputOffset = 0;
+        let attachmentSeq = 0;
+        let closing = false;
+        let lastKeepaliveAt = 0;
+        let pendingInput = null;
+        const identityAuth = () => ({ ...(0, data_provider_1.getClientIdentityAuth)(), clientPlatform: 'cli',
+            clientOs: process.platform === 'darwin' ? 'macos' : process.platform });
         const wsOrigin = (0, agentic_stream_1.toWebSocketOrigin)(options.baseURL);
+        const handshakeAuth = (token, callback) => {
+            // Resolve a fresh proof after token renewal on every reconnect. Never
+            // reuse the original handoff token or its single-use DPoP proof.
+            const auth = (0, dpop_auth_1.socketAuthWithDpop)({ token, ...identityAuth() }, wsOrigin);
+            if (typeof auth === 'function')
+                auth(callback);
+            else
+                callback(auth);
+        };
         const socket = connect(wsOrigin, {
             path: '/ws/agentic',
-            // OSK-12020 — a DPoP-bound token proves possession on every handshake.
-            auth: (0, dpop_auth_1.socketAuthWithDpop)({
-                token: options.token,
-                ...(0, data_provider_1.getClientIdentityAuth)(),
-                clientPlatform: 'cli',
-                clientOs: process.platform === 'darwin' ? 'macos' : process.platform,
-            }, wsOrigin),
-            transports: ['websocket'],
-            // A reconnect cannot resume a channel whose admission line the daemon
-            // revoked on socket death — say it ended and let ssh retry fresh.
-            reconnection: false,
+            auth: options.getToken ? (callback) => {
+                void options.getToken().then((token) => handshakeAuth(token, callback), () => {
+                    finish(1, 'Could not renew SSH authentication. Restore skrr login and connect again.');
+                });
+            } : (0, dpop_auth_1.socketAuthWithDpop)({ token: options.token, ...identityAuth() }, wsOrigin),
+            transports: ['websocket'], reconnection: true,
+            reconnectionDelay: 1000, reconnectionDelayMax: 2000,
         });
-        const startTimer = setTimeout(() => {
-            finish(1, 'The machine did not answer the SSH channel in time. Its daemon may be busy or offline.');
-        }, exports.SSH_START_TIMEOUT_MS);
-        const onInput = (chunk) => {
+        const startTimer = setTimeout(() => finish(1, 'The machine did not answer the SSH channel in time. Its daemon may be busy or offline.'), exports.SSH_START_TIMEOUT_MS);
+        function sendPendingInput() {
+            if (closing || !online || !attached || !pendingInput || finished)
+                return;
+            socket.emit('dedicated:ssh:data', { channelId, data: pendingInput.bytes.toString('base64'),
+                resumeV2: true, epoch, generation, offset: pendingInput.offset });
+        }
+        function pumpInput() {
+            if (closing || !started || !resumable || !online || !attached || pendingInput || finished)
+                return;
+            // Explicit reads bound retained input even if ssh writes a large buffer.
+            const available = input.readableLength;
+            if (!available)
+                return;
+            const bytes = input.read(Math.min(16 * 1024, available));
+            if (!bytes?.length)
+                return;
+            pendingInput = { bytes: Buffer.from(bytes), offset: inputOffset, firstSentAt: Date.now() };
+            sendPendingInput();
+        }
+        const onLegacyInput = (chunk) => {
+            if (!online || finished)
+                return;
             const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
             socket.emit('dedicated:ssh:data', { channelId, data: bytes.toString('base64') });
         };
-        function cleanup() {
-            clearTimeout(startTimer);
-            input.off('data', onInput);
-            input.off('end', onInputEnded);
-            input.off('close', onInputEnded);
-            output.off('error', onOutputError);
-            input.pause();
+        function sendResume() {
+            if (online && started && resumable && !attached && !finished) {
+                socket.emit('dedicated:ssh:resume', { leaseId: options.leaseId, channelId, resumeProof, epoch, generation, attachmentSeq });
+            }
+        }
+        function keepalive() {
+            if (started && resumable && attached && online && !finished && Date.now() - lastKeepaliveAt >= 10_000) {
+                lastKeepaliveAt = Date.now();
+                socket.emit('dedicated:ssh:keepalive', { channelId, epoch });
+            }
         }
-        // The ssh client exiting is visible ONLY as stdin EOF and an EPIPE on
-        // stdout — sshd cannot tell the ProxyCommand died until its socket sees
-        // the stop or the transport drops. Listen for both so the channel, and
-        // the daemon's key admission, end when ssh does instead of at idle
-        // timeout.
+        const ticker = setInterval(() => {
+            if (finished)
+                return;
+            const now = Date.now();
+            if ((recoveringSince !== null && now - recoveringSince >= recoveryMs) ||
+                (pendingInput && now - pendingInput.firstSentAt >= recoveryMs)) {
+                finish(1, 'SSH connection recovery timed out; connect again.');
+                return;
+            }
+            if (!online && started && resumable && socket.active === false)
+                socket.connect();
+            sendResume();
+            sendPendingInput();
+            keepalive();
+        }, 2000);
+        ticker.unref?.();
         const onInputEnded = () => finish(0);
         const onOutputError = () => finish(1);
         input.once('end', onInputEnded);
@@ -329,25 +385,44 @@ function runSshProxy(options) {
             if (finished)
                 return;
             finished = true;
-            cleanup();
+            clearTimeout(startTimer);
+            clearInterval(ticker);
+            input.off('data', onLegacyInput);
+            input.off('readable', pumpInput);
+            input.off('end', onInputEnded);
+            input.off('close', onInputEnded);
+            output.off('error', onOutputError);
+            input.pause();
+            pendingInput = null;
             if (notice)
                 errorOutput.write(`${notice}\n`);
-            if (started)
-                socket.emit('dedicated:ssh:stop', { channelId });
+            // Never queue an offline stop that might arrive after another attachment.
+            if (started && online)
+                socket.emit('dedicated:ssh:stop', { channelId, ...(resumable ? { epoch } : {}) });
             socket.disconnect();
             resolve(code);
         }
-        socket.on('connect_error', (err) => {
-            finish(1, `Could not connect to skrr: ${err.message}`);
+        socket.on('connect_error', (error) => {
+            if (finished || (started && resumable))
+                return;
+            finish(1, `Could not connect to skrr: ${error.message}`);
         });
         socket.on('connect', () => {
-            socket.emit('dedicated:ssh:start', {
-                leaseId: options.leaseId,
-                channelId,
-                keyType: identity.keyType,
-                keyBlob: identity.keyBlob,
-                receiverAckV1: true,
-            });
+            if (finished)
+                return;
+            online = true;
+            if (started) {
+                sendResume();
+                return;
+            }
+            if (startSent) {
+                finish(1, 'SSH admission was interrupted before confirmation; connect again.');
+                return;
+            }
+            startSent = true;
+            socket.emit('dedicated:ssh:start', { leaseId: options.leaseId, channelId,
+                keyType: identity.keyType, keyBlob: identity.keyBlob, receiverAckV1: true,
+                resumeV2: true, resumeProof, epoch });
         });
         socket.on('dedicated:ssh:start:ack', (ack) => {
             if (!ack || ack.channelId !== channelId || started || finished)
@@ -356,48 +431,142 @@ function runSshProxy(options) {
                 finish(1, describeSshStartRefusal(ack));
                 return;
             }
+            if (ack.resumeV2 === true) {
+                if (ack.epoch !== epoch || !Number.isSafeInteger(ack.generation) || Number(ack.generation) < 1 ||
+                    (generation !== null && generation !== ack.generation)) {
+                    finish(1, 'Invalid SSH stream admission.');
+                    return;
+                }
+                resumable = true;
+                generation = ack.generation;
+            }
             started = true;
+            attached = true;
             clearTimeout(startTimer);
-            // The instance's keys, attested by the channel — write them before the
-            // first protocol byte flows so ssh's host-key check reads the new file.
-            // `host` is what ssh asks about (`%h`), so the pin goes under the alias;
-            // a daemon that reported no keys becomes an honest StrictHostKeyChecking
-            // refusal, never a silent TOFU.
             const host = `${options.leaseId}${exports.SSH_HOST_SUFFIX}`;
-            if (!writeHosts(host, ack.hostKeys)) {
+            if (!writeHosts(host, ack.hostKeys))
                 errorOutput.write('[skrr ssh] warning: the machine reported no host keys; the connection will be refused if none are pinned\n');
+            if (resumable) {
+                input.pause();
+                input.on('readable', pumpInput);
+                keepalive();
+                pumpInput();
+            }
+            else {
+                input.on('data', onLegacyInput);
+                input.resume();
+            }
+        });
+        socket.on('dedicated:ssh:resume:ack', (ack) => {
+            if (!ack || ack.channelId !== channelId || ack.epoch !== epoch || !started || !resumable || finished || attached)
+                return;
+            if (!ack.ok) {
+                if (ack.retryable === true)
+                    return;
+                finish(1, ack.error || 'The existing SSH channel cannot resume.');
+                return;
+            }
+            if (ack.resumeV2 !== true || ack.generation !== generation) {
+                finish(1, 'Invalid SSH resume admission.');
+                return;
+            }
+            if (ack.closed === true) {
+                finish(ack.failed === true ? 1 : 0);
+                return;
+            }
+            closing = ack.closing === true;
+            attached = true;
+            recoveringSince = null;
+            lastKeepaliveAt = 0;
+            keepalive();
+            sendPendingInput();
+            pumpInput();
+        });
+        socket.on('dedicated:ssh:input:ack', (ack) => {
+            if (finished || !resumable || !pendingInput || !attached || ack?.channelId !== channelId ||
+                ack.epoch !== epoch || ack.generation !== generation || ack.offset !== pendingInput.offset)
+                return;
+            if (!ack.ok) {
+                finish(1, ack.error || 'The SSH input stream was refused.');
+                return;
+            }
+            if (ack.nextOffset !== pendingInput.offset + pendingInput.bytes.length) {
+                finish(1, 'Invalid SSH input acknowledgment.');
+                return;
             }
-            input.resume();
-            input.on('data', onInput);
+            inputOffset = ack.nextOffset;
+            pendingInput = null;
+            pumpInput();
         });
-        socket.on('dedicated:ssh:data', (frame, receipt) => {
-            if (!frame || frame.channelId !== channelId || finished)
+        socket.on('dedicated:ssh:data', async (frame, receipt) => {
+            if (!frame || frame.channelId !== channelId || finished || typeof frame.data !== 'string' || !frame.data.length)
                 return;
-            if (typeof frame.data === 'string' && frame.data.length > 0) {
+            try {
                 const bytes = Buffer.from(frame.data, 'base64');
-                if (typeof receipt === 'function') {
-                    // A frame can precede start-ack (sshd's banner). The owned channel
-                    // already advertised support; confirm only when stdout flushed.
-                    output.write(bytes, (error) => {
-                        receipt({ channelId, ok: !error && !finished });
-                        if (error)
-                            finish(1, 'Could not write SSH output.');
-                    });
+                if (frame.resumeV2 === true) {
+                    if (frame.epoch !== epoch)
+                        return;
+                    if (!Number.isSafeInteger(frame.generation) || Number(frame.generation) < 1 ||
+                        (generation !== null && frame.generation !== generation) || bytes.toString('base64') !== frame.data) {
+                        throw new Error('invalid SSH output frame');
+                    }
+                    generation ??= frame.generation;
+                    const nextOffset = await receiver.receive(frame.offset, bytes, (value) => new Promise((done, reject) => output.write(value, (error) => error ? reject(error) : done())));
+                    receipt?.({ channelId, ok: !finished, epoch: frame.epoch, nextOffset });
                 }
                 else {
-                    output.write(bytes);
+                    if (resumable)
+                        throw new Error('unsequenced output on resumable SSH stream');
+                    if (typeof receipt === 'function') {
+                        output.write(bytes, (error) => {
+                            receipt({ channelId, ok: !error && !finished });
+                            if (error)
+                                finish(1, 'Could not write SSH output.');
+                        });
+                    }
+                    else
+                        output.write(bytes);
                 }
             }
+            catch {
+                receipt?.({ channelId, ok: false, epoch: frame.epoch });
+                finish(1, 'Could not preserve the SSH output stream.');
+            }
         });
-        socket.on('dedicated:ssh:closed', (frame) => {
-            if (!frame || frame.channelId !== channelId)
+        socket.on('dedicated:ssh:closed', (frame, receipt) => {
+            if (!frame || frame.channelId !== channelId || (frame.epoch && frame.epoch !== epoch))
                 return;
-            finish(0, frame.reason ? `[ssh channel closed: ${frame.reason}]` : undefined);
+            receipt?.({ channelId, epoch: frame.epoch, ok: true });
+            finish(frame.failed === true ? 1 : 0, frame.reason ? `[ssh channel closed: ${frame.reason}]` : undefined);
+        });
+        function beginRecovery() {
+            if (finished || !attached)
+                return;
+            attached = false;
+            input.pause();
+            epoch = (0, node_crypto_1.randomUUID)();
+            attachmentSeq++;
+            if (recoveringSince === null) {
+                recoveringSince = Date.now();
+                errorOutput.write('[skrr ssh] connection interrupted; restoring the existing SSH stream\n');
+            }
+        }
+        socket.on('dedicated:ssh:lost', (frame) => {
+            if (frame?.channelId !== channelId || frame.epoch !== epoch || !resumable || finished)
+                return;
+            beginRecovery();
+            sendResume();
         });
         socket.on('disconnect', () => {
             if (finished)
                 return;
-            finish(started ? 1 : 1, '[lost the connection to skrr; the SSH channel has ended]');
+            online = false;
+            input.pause();
+            if (!started || !resumable) {
+                finish(1, '[lost the connection to skrr; the SSH channel has ended]');
+                return;
+            }
+            beginRecovery();
         });
     });
 }

package/dist/lib/node-adapter.js

@@ -202,7 +202,7 @@ function createNodeAdapter(opts = {}) {
             return false;
         // Never refresh a CI token — they're static by construction.
         const { token, kind } = currentCredential();
-        if (!token || kind === 'ci')
+        if (!token || (0, auth_core_1.isStaticTokenKind)(kind))
             return false;
         if (refreshInFlight)
             return refreshInFlight;
@@ -241,7 +241,7 @@ function createNodeAdapter(opts = {}) {
         if (process.env.OVERSKY_SKIP_DAEMON_BROKER === '1')
             return false;
         const cred = currentCredential();
-        if (cred.kind === 'ci')
+        if ((0, auth_core_1.isStaticTokenKind)(cred.kind))
             return false;
         // An operator-supplied `--token` is that operator's explicit
         // authority: when the server refuses it, the honest answer is the

package/dist/lib/publisher-profile-flags.d.ts

@@ -0,0 +1,19 @@
+import type { PublisherProfileDraft } from '@skrr-ai/data-provider';
+/**
+ * Shared flags for `skrr store publishers profile *`.
+ *
+ * `--publish-as` names a workspace you publish for; omitted, the console is
+ * your personal publisher profile. The server derives the actual principal —
+ * this only selects which of your profiles to address.
+ */
+export declare const publishAsFlag: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+export declare const jsonFlag: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+/** A profile draft is a document; read it from a JSON file, never from argv. */
+export declare function readDraftFile(file: string): PublisherProfileDraft;
+/**
+ * The CAS revision a state change applies to. Publish, hide and restore act
+ * on whatever the draft is NOW, so reading it immediately before the write is
+ * the intent; a caller holding a specific revision passes it and the server
+ * refuses a stale one.
+ */
+export declare function currentRevision(publishAs?: string, explicit?: number): Promise<number>;

package/dist/lib/publisher-profile-flags.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonFlag = exports.publishAsFlag = void 0;
+exports.readDraftFile = readDraftFile;
+exports.currentRevision = currentRevision;
+const node_fs_1 = require("node:fs");
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+/**
+ * Shared flags for `skrr store publishers profile *`.
+ *
+ * `--publish-as` names a workspace you publish for; omitted, the console is
+ * your personal publisher profile. The server derives the actual principal —
+ * this only selects which of your profiles to address.
+ */
+exports.publishAsFlag = core_1.Flags.string({
+    description: 'Workspace id to act for (omit for your personal publisher profile)',
+});
+exports.jsonFlag = core_1.Flags.boolean({ description: 'Output as JSON' });
+/** A profile draft is a document; read it from a JSON file, never from argv. */
+function readDraftFile(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`Could not read a JSON draft from ${file}: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${file} must contain a JSON object (the profile draft)`);
+    }
+    const doc = parsed;
+    // Accept either the bare draft or the `profile show --json` envelope's draft.
+    const nested = doc.profile?.draft ?? doc.draft;
+    return (nested && typeof nested === 'object' ? nested : doc);
+}
+/**
+ * The CAS revision a state change applies to. Publish, hide and restore act
+ * on whatever the draft is NOW, so reading it immediately before the write is
+ * the intent; a caller holding a specific revision passes it and the server
+ * refuses a stale one.
+ */
+async function currentRevision(publishAs, explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    const { profile } = await data_provider_1.dataService.getStorePublisherProfileEditor(publishAs);
+    return profile.revision;
+}

package/dist/lib/refresh.d.ts

@@ -47,7 +47,7 @@ export interface EnsureFreshCliCredentialResult {
     pair?: TokenPair;
     /** Stable diagnostic code; never contains token or server response text. */
     refreshFailureCode?: string;
-    skippedReason?: 'no_token' | 'ci_token' | 'external_source' | 'env_override' | 'bare_mode' | 'fresh' | 'no_refresh_token' | 'refresh_failed';
+    skippedReason?: 'no_token' | 'ci_token' | 'personal_access_token' | 'external_source' | 'env_override' | 'bare_mode' | 'fresh' | 'no_refresh_token' | 'refresh_failed';
 }
 /**
  * Ensure the active CLI credential has enough remaining lifetime for a

package/dist/lib/refresh.js

@@ -94,7 +94,7 @@ function canMutatePersistedCredential(credential, bareMode) {
         return false;
     if (bareMode)
         return false;
-    if (credential.kind === 'ci')
+    if ((0, auth_core_1.isStaticTokenKind)(credential.kind))
         return false;
     // These sources are operator-owned or generated on demand. Never rotate
     // them into the local keychain/file store behind the operator's back.
@@ -120,6 +120,11 @@ async function ensureFreshCliCredential(opts = {}) {
     if (credential.kind === 'ci') {
         return { credential, refreshed: false, skippedReason: 'ci_token' };
     }
+    // A personal access token is static by construction (OSK-13208): there is
+    // no refresh family behind it, so there is nothing to rotate.
+    if (credential.kind === 'pat') {
+        return { credential, refreshed: false, skippedReason: 'personal_access_token' };
+    }
     if (!canMutatePersistedCredential(credential, Boolean(opts.bareMode))) {
         return { credential, refreshed: false, skippedReason: 'external_source' };
     }

package/dist/lib/ssh-ordered-bytes.d.ts

@@ -0,0 +1,8 @@
+/** A bounded receiver for a retryable SSH byte stream. One frame may be
+ * outstanding. A lost acknowledgment may repeat that exact frame, never its
+ * bytes; an overlapping, changed, or skipped frame is a stream error. */
+export declare class SshOrderedBytes {
+    nextOffset: number;
+    private last?;
+    receive(offset: number, bytes: Buffer, write: (bytes: Buffer) => Promise<void>): Promise<number>;
+}

package/dist/lib/ssh-ordered-bytes.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SshOrderedBytes = void 0;
+/** A bounded receiver for a retryable SSH byte stream. One frame may be
+ * outstanding. A lost acknowledgment may repeat that exact frame, never its
+ * bytes; an overlapping, changed, or skipped frame is a stream error. */
+class SshOrderedBytes {
+    nextOffset = 0;
+    last;
+    receive(offset, bytes, write) {
+        if (!Number.isSafeInteger(offset) || offset < 0 || bytes.length < 1 || bytes.length > 16 * 1024 ||
+            !Number.isSafeInteger(offset + bytes.length)) {
+            return Promise.reject(new Error('invalid SSH stream frame'));
+        }
+        if (this.last?.offset === offset) {
+            return this.last.bytes.equals(bytes)
+                ? this.last.written
+                : Promise.reject(new Error('changed SSH stream replay'));
+        }
+        if (offset !== this.nextOffset)
+            return Promise.reject(new Error('SSH stream offset mismatch'));
+        const retained = Buffer.from(bytes);
+        const written = Promise.resolve().then(() => write(retained)).then(() => {
+            this.nextOffset = offset + retained.length;
+            return this.nextOffset;
+        });
+        this.last = { offset, bytes: retained, written };
+        return written;
+    }
+}
+exports.SshOrderedBytes = SshOrderedBytes;

package/dist/lib/usd-micros.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse a user-typed USD amount ("5", "2.50") into integer micros.
+ *
+ * Integer arithmetic on the decimal STRING, never `Number(x) * 1e6`: binary
+ * floating point turns 0.29 into 289999.99… and a money path that truncates
+ * that charges a micro less — or, rounded the other way, a micro more.
+ * Returns null for anything that is not a positive amount with ≤ 2 decimals.
+ */
+export declare function usdToMicros(amount: string): number | null;

package/dist/lib/usd-micros.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usdToMicros = usdToMicros;
+/**
+ * Parse a user-typed USD amount ("5", "2.50") into integer micros.
+ *
+ * Integer arithmetic on the decimal STRING, never `Number(x) * 1e6`: binary
+ * floating point turns 0.29 into 289999.99… and a money path that truncates
+ * that charges a micro less — or, rounded the other way, a micro more.
+ * Returns null for anything that is not a positive amount with ≤ 2 decimals.
+ */
+function usdToMicros(amount) {
+    const trimmed = amount.trim();
+    if (!/^\d+(\.\d{1,2})?$/.test(trimmed))
+        return null;
+    const [whole, frac = ''] = trimmed.split('.');
+    const cents = Number(whole) * 100 + Number(frac.padEnd(2, '0'));
+    if (!Number.isSafeInteger(cents) || cents <= 0)
+        return null;
+    return cents * 10_000;
+}

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/credentialResolver.d.ts

@@ -13,8 +13,11 @@
  * Precedence (high → low):
  *
  *   1. flag         — `--token <jwt>` CLI flag (debugging)
- *   2. env-token    — `OVERSKY_TOKEN` env (CI / static; Phase I adds
- *                     server-side scope=ci validation)
+ *   2. env-token    — `OVERSKY_TOKEN` (CI / static). The CLI also reads
+ *                     `SKRR_TOKEN` via `envTokenNames`; `OVERSKY_TOKEN` wins
+ *                     when both are set, matching the CLI config overlay. A
+ *                     personal access token (`osk_pat_*`) is the credential
+ *                     CI should put here.
  *   3. auth-helper  — `OVERSKY_AUTH_HELPER` script output (rotating
  *                     creds — Vault, AWS SM, internal SSO proxy)
  *   4. fd-handoff   — `OVERSKY_AUTH_FD` parent→child IPC (Electron
@@ -64,6 +67,12 @@ export interface CredentialResolverOptions {
      * string to use that value directly.
      */
     envTokenOverride?: string | null;
+    /**
+     * Environment variables read by the env-token slot, in precedence order.
+     * Defaults to `['OVERSKY_TOKEN']`. The CLI passes
+     * `['OVERSKY_TOKEN', 'SKRR_TOKEN']` (OSK-13208).
+     */
+    envTokenNames?: readonly string[];
     /** Test/explicit override for `OVERSKY_AUTH_HELPER` env. Same semantics. */
     authHelperPathOverride?: string | null;
     /**
@@ -143,6 +152,8 @@ export interface AuthHelperSentinelInfo {
  *                  (POST /api/daemons/token), MUST NOT schedule refresh,
  *                  and on auth failure exits 75 with a CI-specific error
  *                  rather than writing needs-reauth.json.
+ *   - 'pat'      — personal access token (`osk_pat_*`, OSK-13208): a static
+ *                  bearer used AS the user by the CLI. Never refreshed.
  *   - 'install'  — short-lived web-minted JWT with `scope=daemon-install`.
  *                  The daemon exchanges it through the same /api/daemons/token
  *                  bootstrap path, persists only the returned daemon
@@ -157,9 +168,17 @@ export interface AuthHelperSentinelInfo {
  * The kill switch `OVERSKY_DISABLE_CI_TOKEN_RESOLVER=1` forces every token to
  * `'standard'` for triage purposes.
  */
-export type TokenKind = 'standard' | 'ci' | 'install';
+export type TokenKind = 'standard' | 'ci' | 'install' | 'pat';
 /** CI-token plaintext prefix; mirrors api/server/services/Auth/daemonCiTokens.js. */
 export declare const CI_TOKEN_PREFIX = "osk_ci_";
+/** Personal-access-token prefix; mirrors api/server/services/Auth/personalAccessTokens.js. */
+export declare const PERSONAL_ACCESS_TOKEN_PREFIX = "osk_pat_";
+/**
+ * True for a kind whose token is static by construction: never refreshed,
+ * never rotated into a store. Like `TokenKind` itself this selects a local
+ * code path and grants nothing.
+ */
+export declare function isStaticTokenKind(kind: TokenKind): boolean;
 /**
  * Classify a token by local shape. Pure function; safe to call on any string
  * (including `null`-coerced empty). Returns `'standard'` for empty input