@skrr-ai/cli 0.1.47 → 0.1.49

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

@@ -0,0 +1,136 @@
+import { io, type Socket } from 'socket.io-client';
+/**
+ * Owner SSH to a Dedicated Runtime — SSH protocol over the admitted relay.
+ *
+ * Design: docs/architecture/dedicated-runtime-ssh-access-2026-09-21.md.
+ *
+ * This module is the ProxyCommand end of the arrangement. `ssh` speaks its
+ * binary protocol to a ProxyCommand's stdio; `runSshProxy` connects the CLI's
+ * authenticated socket, asks the API for a channel on the lease
+ * (`dedicated:ssh:start`, carrying an ephemeral public key the daemon admits
+ * for this one channel), and then pipes bytes. Nothing here authenticates the
+ * MACHINE — the API admission does — and nothing here authenticates the
+ * CLIENT to sshd — the daemon's admission of the public key does, for exactly
+ * as long as the channel lives.
+ *
+ * Per-device files under ~/.skrr/ssh/ (one identity, one pin file, every
+ * lease — the config block is a wildcard `Host rtl_*.skrr`, so setup is
+ * once-ever, not once-per-lease):
+ *
+ *   id_ed25519(.pub)  the identity this device offers. It is NOT "the key to
+ *                     the machine" — it opens nothing unless the daemon
+ *                     admitted it for a live channel, and the daemon revokes
+ *                     it the moment the channel ends. Losing it loses nothing
+ *                     that was not already a logged-in CLI.
+ *   known_hosts       the host's line is rewritten on every connect from the
+ *                     host keys the daemon just read off THIS instance's
+ *                     /etc/ssh — carried inside the admitted, generation-
+ *                     fenced channel, so the usual first-connect TOFU
+ *                     question never exists, and a replaced machine (new host
+ *                     keys, same workspace) is a silent update rather than a
+ *                     MITM warning.
+ */
+export declare const SSH_HOST_SUFFIX = ".skrr";
+export declare const SSH_USER = "skrr-workload";
+export declare const SSH_START_TIMEOUT_MS = 30000;
+/** The managed block's markers in ~/.ssh/config — one bounded, owned region. */
+export declare const SSH_CONFIG_BEGIN = "# >>> skrr dedicated runtime >>>";
+export declare const SSH_CONFIG_END = "# <<< skrr dedicated runtime <<<";
+export declare class DedicatedSshError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** The lease a ProxyCommand host names: `rtl_x.skrr` or a bare `rtl_x`. */
+export declare function leaseIdForSshHost(host: string): string | null;
+export declare function sshDir(home?: string): string;
+/**
+ * The identity key this device offers to any lease, created on first use.
+ * 0600 in a 0700 directory; `ssh-keygen` is on every machine that has `ssh`,
+ * which is every machine this feature runs on. Per-device by design (§8): the
+ * grant is the channel admission, not the key — one keypair for the device is
+ * the whole surface, so there is nothing per-lease to rotate or lose.
+ */
+export declare function ensureSshIdentity(home?: string): {
+    privateKey: string;
+    publicKey: string;
+    keyType: string;
+    keyBlob: string;
+};
+/**
+ * Rewrite `host`'s lines in the shared known_hosts from keys carried by the
+ * admitted channel. Other leases' pins are kept — each connect replaces only
+ * its own host's rows, atomically. Returns false when the daemon reported no
+ * keys: the caller proceeds, and StrictHostKeyChecking=yes surfaces the gap
+ * honestly rather than silently accepting a key nobody attested.
+ */
+export declare function writeKnownHosts(host: string, hostKeys: {
+    type: string;
+    key: string;
+}[] | undefined, home?: string): boolean;
+export declare function knownHostsPath(home?: string): string;
+/**
+ * The ProxyCommand string OpenSSH runs, quoted for the shell OpenSSH applies
+ * to it: `/bin/sh -c` on POSIX (single quotes), `cmd.exe /c` on Windows
+ * (double quotes). `argv[1]` is the CLI's entry script (bin/run.js), so this
+ * re-invokes whatever binary the user called — installed or in dev.
+ */
+export declare function sshProxyCommand(platform?: NodeJS.Platform): string;
+/**
+ * The managed `Host` block — one wildcard stanza covers every lease, so the
+ * user installs it once and `ssh rtl_<id>.skrr` (and scp, rsync, Remote-SSH)
+ * works for every machine they ever lease.
+ *
+ * `StrictHostKeyChecking yes`, deliberately not accept-new: the host key is
+ * pinned by the proxy from the admitted channel BEFORE the handshake reads
+ * the file, so "yes" costs nothing and an unattested key can never be
+ * silently accepted. `IdentitiesOnly` keeps the user's real agent keys from
+ * being offered — they are never admitted, and offering them would just
+ * spend `MaxAuthTries`. Paths are absolute so the block stays correct even
+ * if the user's HOME moves.
+ */
+export declare function sshConfigBlock(home?: string): string;
+/**
+ * Install the managed block into ~/.ssh/config between the skrr markers — a
+ * bounded, owned region of a file the user owns (the control-surface rule).
+ *
+ * Refuses — rather than edits — when the markers exist but cannot bound a
+ * region: one marker alone, out of order, or duplicated (a hand-edited file,
+ * or another tool already using these strings). Guessing at a corrupted
+ * region risks writing over the user's own Host blocks; a refusal names
+ * exactly what to fix.
+ */
+export declare function installSshConfigBlock(home?: string): {
+    configPath: string;
+    changed: boolean;
+};
+export interface SshStartAck {
+    channelId?: string;
+    ok?: boolean;
+    error?: string;
+    code?: string;
+    hostKeys?: {
+        type: string;
+        key: string;
+    }[];
+}
+export interface SshProxyOptions {
+    baseURL: string;
+    token: string;
+    leaseId: string;
+    input: NodeJS.ReadStream;
+    output: NodeJS.WriteStream;
+    /** Diagnostics; never stdout — ssh reads stdout as protocol bytes. */
+    errorOutput: NodeJS.WritableStream;
+    ttlSeconds?: number;
+    /** Injected for tests. */
+    connect?: (url: string, opts: Parameters<typeof io>[1]) => Socket;
+    /** Injected for tests. */
+    writeKnownHosts?: typeof writeKnownHosts;
+}
+export declare function describeSshStartRefusal(ack: SshStartAck): string;
+/**
+ * Bridge stdio to one SSH channel for as long as it lives. Used as
+ * `ProxyCommand`: ssh writes the protocol to our stdin and reads it from our
+ * stdout. Resolves when the channel ends.
+ */
+export declare function runSshProxy(options: SshProxyOptions): Promise<number>;

package/dist/lib/dedicated-ssh.js

@@ -0,0 +1,387 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DedicatedSshError = exports.SSH_CONFIG_END = exports.SSH_CONFIG_BEGIN = exports.SSH_START_TIMEOUT_MS = exports.SSH_USER = exports.SSH_HOST_SUFFIX = void 0;
+exports.leaseIdForSshHost = leaseIdForSshHost;
+exports.sshDir = sshDir;
+exports.ensureSshIdentity = ensureSshIdentity;
+exports.writeKnownHosts = writeKnownHosts;
+exports.knownHostsPath = knownHostsPath;
+exports.sshProxyCommand = sshProxyCommand;
+exports.sshConfigBlock = sshConfigBlock;
+exports.installSshConfigBlock = installSshConfigBlock;
+exports.describeSshStartRefusal = describeSshStartRefusal;
+exports.runSshProxy = runSshProxy;
+const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+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");
+/**
+ * Owner SSH to a Dedicated Runtime — SSH protocol over the admitted relay.
+ *
+ * Design: docs/architecture/dedicated-runtime-ssh-access-2026-09-21.md.
+ *
+ * This module is the ProxyCommand end of the arrangement. `ssh` speaks its
+ * binary protocol to a ProxyCommand's stdio; `runSshProxy` connects the CLI's
+ * authenticated socket, asks the API for a channel on the lease
+ * (`dedicated:ssh:start`, carrying an ephemeral public key the daemon admits
+ * for this one channel), and then pipes bytes. Nothing here authenticates the
+ * MACHINE — the API admission does — and nothing here authenticates the
+ * CLIENT to sshd — the daemon's admission of the public key does, for exactly
+ * as long as the channel lives.
+ *
+ * Per-device files under ~/.skrr/ssh/ (one identity, one pin file, every
+ * lease — the config block is a wildcard `Host rtl_*.skrr`, so setup is
+ * once-ever, not once-per-lease):
+ *
+ *   id_ed25519(.pub)  the identity this device offers. It is NOT "the key to
+ *                     the machine" — it opens nothing unless the daemon
+ *                     admitted it for a live channel, and the daemon revokes
+ *                     it the moment the channel ends. Losing it loses nothing
+ *                     that was not already a logged-in CLI.
+ *   known_hosts       the host's line is rewritten on every connect from the
+ *                     host keys the daemon just read off THIS instance's
+ *                     /etc/ssh — carried inside the admitted, generation-
+ *                     fenced channel, so the usual first-connect TOFU
+ *                     question never exists, and a replaced machine (new host
+ *                     keys, same workspace) is a silent update rather than a
+ *                     MITM warning.
+ */
+exports.SSH_HOST_SUFFIX = '.skrr';
+exports.SSH_USER = 'skrr-workload';
+exports.SSH_START_TIMEOUT_MS = 30_000;
+/** The managed block's markers in ~/.ssh/config — one bounded, owned region. */
+exports.SSH_CONFIG_BEGIN = '# >>> skrr dedicated runtime >>>';
+exports.SSH_CONFIG_END = '# <<< skrr dedicated runtime <<<';
+const LEASE_ID_PATTERN = /^rtl_[a-z0-9]{8,64}$/;
+const HOSTKEY_TYPES = new Set([
+    'ssh-ed25519',
+    'ssh-rsa',
+    'ecdsa-sha2-nistp256',
+    'ecdsa-sha2-nistp384',
+    'ecdsa-sha2-nistp521',
+]);
+class DedicatedSshError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'DedicatedSshError';
+        this.code = code;
+    }
+}
+exports.DedicatedSshError = DedicatedSshError;
+/** The lease a ProxyCommand host names: `rtl_x.skrr` or a bare `rtl_x`. */
+function leaseIdForSshHost(host) {
+    const value = String(host || '').trim();
+    const bare = value.endsWith(exports.SSH_HOST_SUFFIX) ? value.slice(0, -exports.SSH_HOST_SUFFIX.length) : value;
+    return LEASE_ID_PATTERN.test(bare) ? bare : null;
+}
+function sshDir(home = (0, node_os_1.homedir)()) {
+    return node_path_1.default.join(home, '.skrr', 'ssh');
+}
+/**
+ * The identity key this device offers to any lease, created on first use.
+ * 0600 in a 0700 directory; `ssh-keygen` is on every machine that has `ssh`,
+ * which is every machine this feature runs on. Per-device by design (§8): the
+ * grant is the channel admission, not the key — one keypair for the device is
+ * the whole surface, so there is nothing per-lease to rotate or lose.
+ */
+function ensureSshIdentity(home = (0, node_os_1.homedir)()) {
+    const dir = sshDir(home);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    (0, node_fs_1.chmodSync)(dir, 0o700);
+    const privateKey = node_path_1.default.join(dir, 'id_ed25519');
+    const publicKeyPath = `${privateKey}.pub`;
+    if (!(0, node_fs_1.existsSync)(privateKey) || !(0, node_fs_1.existsSync)(publicKeyPath)) {
+        try {
+            (0, node_child_process_1.execFileSync)('ssh-keygen', [
+                '-q',
+                '-t',
+                'ed25519',
+                '-N',
+                '',
+                '-C',
+                'skrr-ssh-device',
+                '-f',
+                privateKey,
+            ]);
+        }
+        catch (error) {
+            throw new DedicatedSshError(`could not create the SSH identity — is \`ssh-keygen\` installed? (${error instanceof Error ? error.message : error})`, 'SSH_KEYGEN_FAILED');
+        }
+        (0, node_fs_1.chmodSync)(privateKey, 0o600);
+        (0, node_fs_1.chmodSync)(publicKeyPath, 0o644);
+    }
+    const line = (0, node_fs_1.readFileSync)(publicKeyPath, 'utf8').trim();
+    const [keyType, keyBlob] = line.split(/\s+/);
+    if (!keyType || !keyBlob) {
+        throw new DedicatedSshError(`could not read ${publicKeyPath}`, 'SSH_KEY_UNREADABLE');
+    }
+    return { privateKey, publicKey: publicKeyPath, keyType, keyBlob };
+}
+/**
+ * Rewrite `host`'s lines in the shared known_hosts from keys carried by the
+ * admitted channel. Other leases' pins are kept — each connect replaces only
+ * its own host's rows, atomically. Returns false when the daemon reported no
+ * keys: the caller proceeds, and StrictHostKeyChecking=yes surfaces the gap
+ * honestly rather than silently accepting a key nobody attested.
+ */
+function writeKnownHosts(host, hostKeys, home = (0, node_os_1.homedir)()) {
+    if (!Array.isArray(hostKeys) || hostKeys.length === 0)
+        return false;
+    const dir = sshDir(home);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    (0, node_fs_1.chmodSync)(dir, 0o700);
+    const lines = hostKeys
+        .filter((k) => k && HOSTKEY_TYPES.has(k.type) && /^[A-Za-z0-9+/]+=*$/.test(k.key))
+        .map((k) => `${host} ${k.type} ${k.key}`);
+    if (lines.length === 0)
+        return false;
+    const target = node_path_1.default.join(dir, 'known_hosts');
+    let existing = [];
+    try {
+        existing = (0, node_fs_1.readFileSync)(target, 'utf8')
+            .split('\n')
+            .filter((l) => l.trim().length > 0);
+    }
+    catch {
+        /* first connect */
+    }
+    const kept = existing.filter((l) => l.split(/\s+/)[0] !== host);
+    const tmp = `${target}.${process.pid}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, `${[...kept, ...lines].join('\n')}\n`, { mode: 0o600 });
+    (0, node_fs_1.renameSync)(tmp, target);
+    return true;
+}
+function knownHostsPath(home = (0, node_os_1.homedir)()) {
+    return node_path_1.default.join(sshDir(home), 'known_hosts');
+}
+/**
+ * The ProxyCommand string OpenSSH runs, quoted for the shell OpenSSH applies
+ * to it: `/bin/sh -c` on POSIX (single quotes), `cmd.exe /c` on Windows
+ * (double quotes). `argv[1]` is the CLI's entry script (bin/run.js), so this
+ * re-invokes whatever binary the user called — installed or in dev.
+ */
+function sshProxyCommand(platform = process.platform) {
+    // POSIX: sh single-quotes — literal except ', which ends the quote and is
+    // re-entered as '\''. Windows: OpenSSH there hands the command to
+    // `cmd.exe /c`, where ' is not a quote at all — double-quote each word.
+    // Backslashes stay literal (cmd does not treat \ as an escape inside
+    // quotes), and " cannot appear — Windows forbids it in paths.
+    const quote = platform === 'win32'
+        ? (w) => `"${w}"`
+        : (w) => `'${w.split("'").join(`'\\''`)}'`;
+    const words = [process.execPath, process.argv[1]]
+        .filter((w) => typeof w === 'string' && w.length > 0)
+        .map(quote);
+    return `${words.join(' ')} machines dedicated ssh-proxy %h`;
+}
+/**
+ * The managed `Host` block — one wildcard stanza covers every lease, so the
+ * user installs it once and `ssh rtl_<id>.skrr` (and scp, rsync, Remote-SSH)
+ * works for every machine they ever lease.
+ *
+ * `StrictHostKeyChecking yes`, deliberately not accept-new: the host key is
+ * pinned by the proxy from the admitted channel BEFORE the handshake reads
+ * the file, so "yes" costs nothing and an unattested key can never be
+ * silently accepted. `IdentitiesOnly` keeps the user's real agent keys from
+ * being offered — they are never admitted, and offering them would just
+ * spend `MaxAuthTries`. Paths are absolute so the block stays correct even
+ * if the user's HOME moves.
+ */
+function sshConfigBlock(home = (0, node_os_1.homedir)()) {
+    const dir = sshDir(home);
+    return [
+        `Host rtl_*${exports.SSH_HOST_SUFFIX}`,
+        `  User ${exports.SSH_USER}`,
+        `  IdentityFile ${node_path_1.default.join(dir, 'id_ed25519')}`,
+        `  IdentitiesOnly yes`,
+        `  ProxyCommand ${sshProxyCommand()}`,
+        `  UserKnownHostsFile ${node_path_1.default.join(dir, 'known_hosts')}`,
+        `  StrictHostKeyChecking yes`,
+        `  ServerAliveInterval 30`,
+    ].join('\n');
+}
+/**
+ * Install the managed block into ~/.ssh/config between the skrr markers — a
+ * bounded, owned region of a file the user owns (the control-surface rule).
+ *
+ * Refuses — rather than edits — when the markers exist but cannot bound a
+ * region: one marker alone, out of order, or duplicated (a hand-edited file,
+ * or another tool already using these strings). Guessing at a corrupted
+ * region risks writing over the user's own Host blocks; a refusal names
+ * exactly what to fix.
+ */
+function installSshConfigBlock(home = (0, node_os_1.homedir)()) {
+    const configPath = node_path_1.default.join(home, '.ssh', 'config');
+    (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(configPath), { recursive: true, mode: 0o700 });
+    (0, node_fs_1.chmodSync)(node_path_1.default.dirname(configPath), 0o700);
+    const block = `${exports.SSH_CONFIG_BEGIN}\n${sshConfigBlock(home)}\n${exports.SSH_CONFIG_END}`;
+    let text = '';
+    try {
+        text = (0, node_fs_1.readFileSync)(configPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const firstBegin = text.indexOf(exports.SSH_CONFIG_BEGIN);
+    const firstEnd = text.indexOf(exports.SSH_CONFIG_END);
+    const malformed = firstBegin === -1 ||
+        firstEnd === -1 ||
+        firstEnd < firstBegin ||
+        text.indexOf(exports.SSH_CONFIG_BEGIN, firstBegin + 1) !== -1 ||
+        text.indexOf(exports.SSH_CONFIG_END, firstEnd + 1) !== -1;
+    if (text.includes(exports.SSH_CONFIG_BEGIN) || text.includes(exports.SSH_CONFIG_END)) {
+        if (malformed) {
+            throw new DedicatedSshError(`${configPath} has a partial or duplicated skrr block and is not safe to edit. Fix it by hand, or remove the lines containing 'skrr dedicated runtime' and run ssh-config again.`, 'SSH_CONFIG_COLLISION');
+        }
+        const next = text.slice(0, firstBegin) + block + text.slice(firstEnd + exports.SSH_CONFIG_END.length);
+        (0, node_fs_1.writeFileSync)(configPath, next, { mode: 0o600 });
+        return { configPath, changed: next !== text };
+    }
+    let separator = '';
+    if (text.length > 0)
+        separator = text.endsWith('\n\n') ? '' : '\n\n';
+    const next = `${text}${separator}${block}\n`;
+    (0, node_fs_1.writeFileSync)(configPath, next, { mode: 0o600 });
+    return { configPath, changed: true };
+}
+function describeSshStartRefusal(ack) {
+    const code = ack.code || '';
+    if (code === 'DEDICATED_RUNTIME_SSH_UNSUPPORTED') {
+        return (ack.error ||
+            'This machine’s image does not carry SSH support yet. Update it with `skrr machines dedicated update-image <lease-id> --wait`.');
+    }
+    if (code === 'dedicated_runtime_quiesced') {
+        return 'The machine is checkpointing its workspace right now; try again in a moment.';
+    }
+    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_NOT_ASSIGNABLE' || code === 'not_found' || code === 'offline') {
+        return 'The machine is not running or its daemon is not connected. Check it with `skrr machines dedicated show <lease-id>`.';
+    }
+    return ack.error ? `SSH did not start: ${ack.error}` : 'SSH did not start.';
+}
+/**
+ * Bridge stdio to one SSH channel for as long as it lives. Used as
+ * `ProxyCommand`: ssh writes the protocol to our stdin and reads it from our
+ * stdout. Resolves when the channel ends.
+ */
+function runSshProxy(options) {
+    const channelId = `ssh-${(0, node_crypto_1.randomUUID)()}`;
+    const connect = options.connect ?? socket_io_client_1.io;
+    const { input, output, errorOutput } = options;
+    const identity = ensureSshIdentity();
+    const writeHosts = options.writeKnownHosts ?? writeKnownHosts;
+    return new Promise((resolve) => {
+        let started = false;
+        let finished = false;
+        const socket = connect((0, agentic_stream_1.toWebSocketOrigin)(options.baseURL), {
+            path: '/ws/agentic',
+            auth: {
+                token: options.token,
+                ...(0, data_provider_1.getClientIdentityAuth)(),
+                clientPlatform: 'cli',
+                clientOs: process.platform === 'darwin' ? 'macos' : process.platform,
+            },
+            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,
+        });
+        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 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();
+        }
+        // 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 onInputEnded = () => finish(0);
+        const onOutputError = () => finish(1);
+        input.once('end', onInputEnded);
+        input.once('close', onInputEnded);
+        output.once('error', onOutputError);
+        function finish(code, notice) {
+            if (finished)
+                return;
+            finished = true;
+            cleanup();
+            if (notice)
+                errorOutput.write(`${notice}\n`);
+            if (started)
+                socket.emit('dedicated:ssh:stop', { channelId });
+            socket.disconnect();
+            resolve(code);
+        }
+        socket.on('connect_error', (err) => {
+            finish(1, `Could not connect to skrr: ${err.message}`);
+        });
+        socket.on('connect', () => {
+            socket.emit('dedicated:ssh:start', {
+                leaseId: options.leaseId,
+                channelId,
+                keyType: identity.keyType,
+                keyBlob: identity.keyBlob,
+            });
+        });
+        socket.on('dedicated:ssh:start:ack', (ack) => {
+            if (!ack || ack.channelId !== channelId || started || finished)
+                return;
+            if (!ack.ok) {
+                finish(1, describeSshStartRefusal(ack));
+                return;
+            }
+            started = 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)) {
+                errorOutput.write('[skrr ssh] warning: the machine reported no host keys; the connection will be refused if none are pinned\n');
+            }
+            input.resume();
+            input.on('data', onInput);
+        });
+        socket.on('dedicated:ssh:data', (frame) => {
+            if (!frame || frame.channelId !== channelId || finished)
+                return;
+            if (typeof frame.data === 'string' && frame.data.length > 0) {
+                output.write(Buffer.from(frame.data, 'base64'));
+            }
+        });
+        socket.on('dedicated:ssh:closed', (frame) => {
+            if (!frame || frame.channelId !== channelId)
+                return;
+            finish(0, frame.reason ? `[ssh channel closed: ${frame.reason}]` : undefined);
+        });
+        socket.on('disconnect', () => {
+            if (finished)
+                return;
+            finish(started ? 1 : 1, '[lost the connection to skrr; the SSH channel has ended]');
+        });
+    });
+}

package/dist/lib/delegated-cli.js

@@ -77,12 +77,12 @@ function resetDelegatedCliCredentialCache() {
     _cached = null;
 }
 /**
- * Walk `err.cause` / `err.errors[]` looking for a `code: 'ECONNREFUSED'`.
+ * Walk `err.cause` / `err.errors[]` looking for an errno-style `code`.
  * Node's `fetch` throws a `TypeError('fetch failed')` whose `cause` is either
  * a plain `Error` with `code` set, or an `AggregateError` whose `errors[]`
  * carry it (dual-stack retries). Neither shape is visible at the top level.
  */
-function isConnectionRefusedError(err) {
+function fetchTransportCode(err) {
     const seen = new Set();
     const stack = [err];
     while (stack.length) {
@@ -91,15 +91,18 @@ function isConnectionRefusedError(err) {
             continue;
         seen.add(cur);
         const anyCur = cur;
-        if (anyCur.code === 'ECONNREFUSED')
-            return true;
+        if (typeof anyCur.code === 'string' && anyCur.code.length > 0)
+            return anyCur.code;
         if (anyCur.cause !== undefined)
             stack.push(anyCur.cause);
         if (Array.isArray(anyCur.errors))
             for (const e of anyCur.errors)
                 stack.push(e);
     }
-    return false;
+    return null;
+}
+function isConnectionRefusedError(err) {
+    return fetchTransportCode(err) === 'ECONNREFUSED';
 }
 /**
  * Best-effort probe of the daemon's bootstrap file — the CLI's
@@ -164,6 +167,35 @@ function composeStaleBrokerMessage(brokerUrl) {
         `  unset OVERSKY_DELEGATED_CLI_BROKER_URL OVERSKY_DELEGATED_CLI_CAPABILITY OVERSKY_AUTONOMOUS_SESSION\n` +
         `Subsequent \`skrr\` calls will then auto-broker a fresh credential via the live daemon.`);
 }
+/**
+ * Rewrite a transport-level failure (anything that is not ECONNREFUSED — that
+ * one means a dead daemon, handled above) into a message that names the real
+ * cause and the recovery, instead of the bare `fetch failed` Node surfaces.
+ */
+function composeUnreachableBrokerMessage(brokerUrl, err) {
+    const code = fetchTransportCode(err);
+    if (code === 'EPERM') {
+        // Observed concretely: a Codex-managed session under a seatbelt
+        // workspace-write/read-only profile gets EPERM connecting to
+        // 127.0.0.1 — seatbelt's `network-outbound` denial covers loopback.
+        return (`the OS denied the connection to the delegated CLI broker at ${brokerUrl} (EPERM). ` +
+            `This process is inside a sandbox that blocks outbound network — including ` +
+            `127.0.0.1 (Codex's seatbelt workspace-write/read-only profiles do this). ` +
+            `Re-run with the sandbox's network access enabled, or outside the sandbox. ` +
+            `Unsetting the OVERSKY_DELEGATED_CLI_* vars does not help: the same sandbox ` +
+            `would block the upstream API as well.`);
+    }
+    // undici rejects an aborted fetch with a DOMException named 'AbortError',
+    // which is NOT an `instanceof Error` in Node — check the name structurally.
+    if (err?.name === 'AbortError') {
+        return (`the delegated CLI broker at ${brokerUrl} did not answer within 5s. ` +
+            `The daemon listener is accepting connections but not responding — it may be ` +
+            `wedged; check the daemon and retry.`);
+    }
+    const detail = err instanceof Error ? err.message : String(err);
+    return (`the delegated CLI broker at ${brokerUrl} is unreachable: ${detail}` +
+        (code ? ` (${code})` : ''));
+}
 /** Fetch a full-permission CLI access token from the local daemon. */
 async function fetchDelegatedCliCredential(env = process.env, options = {}) {
     if (!isDelegatedCliSession(env))
@@ -197,12 +229,14 @@ async function fetchDelegatedCliCredential(env = process.env, options = {}) {
             // from a live daemon: it means the whole loopback listener is gone, so
             // the capability is unrecoverable rather than transiently unavailable.
             // Rewrite the message so `base-command` surfaces recovery text instead
-            // of a bare `fetch failed`. Any other network error (DNS, TLS,
-            // AbortError, etc.) propagates unchanged.
+            // of a bare `fetch failed`. Other transport errors keep the original as
+            // `cause` but still get a rewritten headline — EPERM (a sandbox denying
+            // loopback), a timeout, and a bare `fetch failed` are different problems
+            // with different remedies.
             if (isConnectionRefusedError(err)) {
-                throw new Error(composeStaleBrokerMessage(brokerUrl));
+                throw new Error(composeStaleBrokerMessage(brokerUrl), { cause: err });
             }
-            throw err;
+            throw new Error(composeUnreachableBrokerMessage(brokerUrl, err), { cause: err });
         }
         if (!res.ok) {
             // A DELIBERATE decline is not a broker failure — WL-5 Step 1.
@@ -220,10 +254,14 @@ async function fetchDelegatedCliCredential(env = process.env, options = {}) {
             // Agent whose daemon cannot rotate its family must surface that rather
             // than quietly degrade, because a degraded credential path is exactly
             // where a human's stored family gets adopted by accident.
-            if (res.status === 403) {
-                const body = (await res.json().catch(() => null));
-                if (body?.code === 'DELEGATED_CLI_CAPABILITY_REJECTED')
-                    return null;
+            const body = (await res.json().catch(() => null));
+            if (res.status === 403 && body?.code === 'DELEGATED_CLI_CAPABILITY_REJECTED')
+                return null;
+            if (res.status === 503 || body?.code === 'DELEGATED_CLI_CREDENTIAL_UNAVAILABLE') {
+                throw new Error(`the daemon's delegated CLI broker is alive but cannot mint a credential ` +
+                    `(HTTP ${res.status}). The daemon cannot reach the auth upstream, holds ` +
+                    `no daemon bearer, or is inside its mint cool-down — check the daemon ` +
+                    `log for [delegated-cli]/[task-token] lines and retry.`);
             }
             throw new Error(`Delegated skrr CLI credential broker returned HTTP ${res.status}.`);
         }