@shardflux/cli 0.15.2 → 0.17.0

package/dist/cli-proxy.js

@@ -0,0 +1,1016 @@
+/**
+ * `shard cli-proxy` (status), `shard cli-proxy import` and the hidden `shard cli-proxy forward`: one hosted
+ * CLIProxyAPI per account (cli-proxy-hub.ts), reached at http://127.0.0.1:8317 on this computer (a launchd agent runs
+ * the forwarder, cli-proxy-forward.ts) and in every VM (the hub info in the machine template; sf-agent forwards there).
+ *
+ * Import moves the user's CLIProxyAPI from this computer: the hub is made from their config, the local copy stops
+ * (only one copy may refresh a login), their auth files go to the hub (never printed), the forwarder takes 127.0.0.1:8317
+ * and the machine template carries the hub info. Onboarding calls `detectLocalCliProxy()` and `importCliProxy(ctx)`.
+ */
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { homedir, userInfo } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { parse as parseYaml } from 'yaml';
+import { AgentStateStore } from "./agent-state.js";
+import { syncAgentConfig } from "./agent-config-sync.js";
+import { CliProxyForwarder, IDENTITY_PATH, hubInfoSource } from "./cli-proxy-forward.js";
+import { ADD_AUTH_SCRIPT, CLI_PROXY_PORT, CLI_PROXY_VM_PORT, HUB_AUTH_DIR, HUB_KEY, HubError, SET_ASIDE_SCRIPT, STOP_SCRIPT, ensureCliProxyHub, hubCallback, readHubInfo, sdkHubCloud, vmHubInfoText, writeHubInfo } from "./cli-proxy-hub.js";
+import { CLI_VERSION } from "./args.js";
+import { UsageError } from "./errors.js";
+import { json } from "./format.js";
+import { progress } from "./progress.js";
+const execute = promisify(execFile);
+export const runProgram = async (program, args) => {
+    try {
+        return (await execute(program, args, { timeout: 15_000, maxBuffer: 4 * 1024 * 1024 })).stdout;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The programs and probes detection, stop and the launchd install use by default. The CLI test support replaces them,
+ * so no test inspects, stops or replaces a CLIProxyAPI or forwarder running on the developer's computer.
+ */
+export const cliProxyTools = {
+    run: runProgram,
+    answers: (port) => portAnswers(port),
+    identity: (port) => forwarderIdentity(port),
+    inVm: () => inShardfluxVm(),
+    kill: (pid) => { process.kill(pid, 'SIGTERM'); },
+};
+/** The launchd agent that keeps the forwarder on 127.0.0.1:8317 on a Mac. */
+export const FORWARD_LABEL = 'dev.shardflux.cli-proxy-forward';
+/** Where every VM finds the hub info (the machine template carries it). */
+// Outside ~/.config/shardflux, which machines and templates never capture (the platform's per-VM state).
+export const VM_HUB_INFO_PATH = '/home/user/.config/shardflux-cli-proxy.json';
+const expandHome = (path, home) => (path === '~' ? home : path.startsWith('~/') ? join(home, path.slice(2)) : path);
+const isFile = (path) => { try {
+    return lstatSync(path).isFile();
+}
+catch {
+    return false;
+} };
+const CLI_PROXY_EXE = /^(cli-proxy-api|cliproxyapi)$/i;
+const FORWARDER_COMMAND = /\bcli-proxy\s+forward\b|\bsf-agent\s+cli-proxy-forward\b/;
+/** The container that publishes `port` (docker ps), when Docker answers. */
+async function findContainer(run, port) {
+    const out = await run('docker', ['ps', '--format', '{{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Ports}}']);
+    for (const line of (out ?? '').split('\n')) {
+        const [id, name, image, ports] = line.split('\t');
+        if (!id || !name || !image || !ports || !new RegExp(`:${port}->`).test(ports))
+            continue;
+        return { id, name, image, cliProxy: /cli-?proxy-?api/i.test(image) || /cli-?proxy-?api/i.test(name) };
+    }
+    return null;
+}
+/** The listening process: pid, command line, executable, and what it is (lsof, ps, docker; null without them). */
+async function findListener(run, port) {
+    const out = await run('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fp']);
+    const pid = Number(/^p(\d+)$/m.exec(out ?? '')?.[1]);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    const command = (await run('ps', ['-o', 'args=', '-p', String(pid)]))?.trim() ?? '';
+    const executable = (await run('ps', ['-o', 'comm=', '-p', String(pid)]))?.trim() || command.split(/\s+/)[0] || '';
+    const forwarder = FORWARDER_COMMAND.test(command);
+    const cliProxy = !forwarder && (CLI_PROXY_EXE.test(basename(executable)) || CLI_PROXY_EXE.test(basename(command.split(/\s+/)[0] ?? '')));
+    const container = forwarder || cliProxy ? null : await findContainer(run, port);
+    return { pid, command, executable, forwarder, cliProxy, container };
+}
+/** The host folders a CLIProxyAPI container mounts as its auth directory and config (docker inspect). */
+async function containerMounts(run, id) {
+    let mounts = [];
+    try {
+        mounts = JSON.parse((await run('docker', ['inspect', '-f', '{{json .Mounts}}', id])) ?? '[]');
+    }
+    catch { /* none */ }
+    const source = (test) => mounts.find((m) => typeof m.Destination === 'string' && typeof m.Source === 'string' && test(m.Destination))?.Source;
+    return { authDir: source((d) => /\/\.cli-proxy-api\/?$/.test(d)) ?? null, config: source((d) => /config\.ya?ml$/.test(d)) ?? null };
+}
+function configFromArgs(command) {
+    return /(?:^|\s)--?config(?:=|\s+)("[^"]+"|'[^']+'|\S+)/.exec(command)?.[1]?.replace(/^["']|["']$/g, '') ?? null;
+}
+const BREW_PREFIXES = ['/opt/homebrew', '/usr/local', '/home/linuxbrew/.linuxbrew'];
+/** CLIProxyAPI's usual config locations: Homebrew's etc (cliproxyapi.conf, cliproxyapi*.yaml), then the home folders. */
+function configCandidates(home, service) {
+    const out = [];
+    for (const prefix of BREW_PREFIXES) {
+        if (service?.kind === 'brew')
+            out.push(join(prefix, 'etc', `${service.formula}.conf`));
+        out.push(join(prefix, 'etc', 'cliproxyapi.conf'));
+        try {
+            for (const name of readdirSync(join(prefix, 'etc')).sort())
+                if (/^cli-?proxy-?api.*\.(ya?ml|conf)$/i.test(name))
+                    out.push(join(prefix, 'etc', name));
+        }
+        catch { /* no Homebrew there */ }
+    }
+    out.push(join(home, '.cli-proxy-api', 'config.yaml'), join(home, '.config', 'cli-proxy-api', 'config.yaml'), join(home, 'cli-proxy-api', 'config.yaml'), join(home, 'CLIProxyAPI', 'config.yaml'));
+    return out;
+}
+/** The Homebrew service or launchd agent whose program is CLIProxyAPI (macOS; never Shardflux's own forwarder). */
+async function findService(run, home, listener) {
+    const dir = join(home, 'Library', 'LaunchAgents');
+    let names;
+    try {
+        names = readdirSync(dir).filter((n) => n.endsWith('.plist') && n !== `${FORWARD_LABEL}.plist`);
+    }
+    catch {
+        return null;
+    }
+    const executable = listener?.command.split(/\s+/)[0] ?? '';
+    for (const name of names.sort()) {
+        const file = join(dir, name);
+        let raw;
+        try {
+            raw = readFileSync(file, 'latin1');
+        }
+        catch {
+            continue;
+        }
+        if (!/cli-?proxy/i.test(raw))
+            continue;
+        const text = await run('plutil', ['-convert', 'json', '-o', '-', file]);
+        let plist;
+        try {
+            plist = JSON.parse(text ?? 'null') ?? {};
+        }
+        catch {
+            continue;
+        }
+        const argv = Array.isArray(plist.ProgramArguments) ? plist.ProgramArguments.map(String) : typeof plist.Program === 'string' ? [plist.Program] : [];
+        const program = argv[0] ?? '';
+        const matches = (executable && (program === executable || basename(program) === basename(executable))) || /^(cliproxyapi|cli-proxy-api)$/i.test(basename(program));
+        if (!matches || typeof plist.Label !== 'string')
+            continue;
+        const formula = /^homebrew\.mxcl\.(.+)$/.exec(plist.Label)?.[1];
+        return formula ? { kind: 'brew', formula, label: plist.Label } : { kind: 'launchd', label: plist.Label, plist: file };
+    }
+    return null;
+}
+/** The auth files of a directory and its subdirectories (CLIProxyAPI walks them all), as paths relative to it. */
+function authFiles(dir) {
+    const out = [];
+    const walk = (rel, depth) => {
+        let names;
+        try {
+            names = readdirSync(join(dir, rel));
+        }
+        catch {
+            return;
+        }
+        for (const name of names.sort()) {
+            const path = rel ? `${rel}/${name}` : name;
+            let st;
+            try {
+                st = lstatSync(join(dir, path));
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory() && depth < 4)
+                walk(path, depth + 1);
+            else if (st.isFile() && name.endsWith('.json') && st.size <= 1024 * 1024)
+                out.push(path);
+        }
+    };
+    walk('', 0);
+    return out;
+}
+function readLogins(authDir) {
+    return authFiles(authDir).map((file) => {
+        try {
+            const doc = JSON.parse(readFileSync(join(authDir, file), 'utf8'));
+            return { file, provider: typeof doc.type === 'string' ? doc.type : null, email: typeof doc.email === 'string' ? doc.email : null };
+        }
+        catch {
+            return { file, provider: null, email: null };
+        }
+    });
+}
+/** The listening port of a CLIProxyAPI config (either layout), or null when it names none. */
+export function configPort(doc) {
+    const o = (doc && typeof doc === 'object' ? doc : {});
+    const server = (o.server && typeof o.server === 'object' ? o.server : {});
+    const port = Number(server.port ?? o.port);
+    return Number.isInteger(port) && port > 0 && port < 65536 ? port : null;
+}
+/**
+ * CLIProxyAPI on this computer: its auth files (provider and email of each), its config and port, the process that
+ * listens there and the service that runs it. Null when there is none of these.
+ */
+export async function detectLocalCliProxy(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? env.HOME ?? homedir();
+    const run = opts.run ?? cliProxyTools.run;
+    const onDefault = await findListener(run, CLI_PROXY_PORT);
+    let configPath = opts.configPath ? expandHome(opts.configPath, home) : null;
+    if (configPath && !isFile(configPath))
+        throw new UsageError(`No CLIProxyAPI config at ${configPath}`);
+    let mountedAuthDir = null;
+    if (onDefault?.container?.cliProxy) {
+        const mounts = await containerMounts(run, onDefault.container.id);
+        if (!configPath && mounts.config && isFile(mounts.config))
+            configPath = mounts.config;
+        mountedAuthDir = mounts.authDir;
+    }
+    if (!configPath && onDefault?.cliProxy) {
+        const fromArgs = configFromArgs(onDefault.command);
+        if (fromArgs) {
+            const cwd = /^n(.+)$/m.exec((await run('lsof', ['-a', '-p', String(onDefault.pid), '-d', 'cwd', '-Fn'])) ?? '')?.[1];
+            const path = fromArgs.startsWith('/') || !cwd ? expandHome(fromArgs, home) : join(cwd, fromArgs);
+            if (isFile(path))
+                configPath = path;
+        }
+    }
+    const darwin = (opts.platform ?? process.platform) === 'darwin';
+    let service = darwin ? await findService(run, home, onDefault) : null;
+    configPath ??= configCandidates(home, service).find(isFile) ?? null;
+    let authDir = join(home, '.cli-proxy-api');
+    let port = CLI_PROXY_PORT;
+    if (configPath) {
+        try {
+            const doc = parseYaml(readFileSync(configPath, 'utf8'));
+            const dir = doc?.['auth-dir'] ?? doc?.oauth?.['auth-dir'];
+            if (typeof dir === 'string' && dir.trim())
+                authDir = expandHome(dir.trim(), home);
+            port = configPort(doc) ?? CLI_PROXY_PORT;
+        }
+        catch { /* the import reports an unreadable config */ }
+    }
+    // A CLIProxyAPI container reads the folder it mounts, whatever its config says inside the container.
+    if (mountedAuthDir && existsSync(mountedAuthDir))
+        authDir = mountedAuthDir;
+    const listener = port === CLI_PROXY_PORT ? onDefault : await findListener(run, port);
+    if (port !== CLI_PROXY_PORT && darwin)
+        service = await findService(run, home, listener) ?? service;
+    const fallback = join(home, '.cli-proxy-api');
+    const authDirs = [authDir, ...(fallback !== authDir && authFiles(fallback).length ? [fallback] : [])];
+    const logins = readLogins(authDir);
+    if (logins.length === 0 && !configPath && !listener?.cliProxy && !listener?.container?.cliProxy)
+        return null;
+    return { authDir, authDirs, logins, configPath, port, listener, service };
+}
+/** The fields of an auth file that say which account, workspace or project it signs in to (CLIProxyAPI 8.0.23). */
+const IDENTITY_FIELDS = ['email', 'user_email', 'account_id', 'chatgpt_account_id', 'account_uuid', 'account.id', 'organization_uuid', 'organization_id', 'org_id', 'workspace_id', 'team_id', 'user_id', 'project_id'];
+/**
+ * Who an auth file signs in as: its provider (`type`) and every identifying field it has (email, account, organization,
+ * workspace, user and project ids), from its JSON. Two files are the same login only when they have the same provider
+ * and the same fields with the same values: one email can sign in to several accounts or workspaces, so a file that
+ * names a different (or one more) account is another login. A file without any is only itself (its path).
+ */
+export function loginIdentity(text, file) {
+    let doc = {};
+    try {
+        const v = JSON.parse(text);
+        if (v && typeof v === 'object')
+            doc = v;
+    }
+    catch { /* not JSON */ }
+    const s = (v) => (typeof v === 'string' && v.trim() ? v.trim().toLowerCase() : typeof v === 'number' && Number.isFinite(v) ? String(v) : null);
+    const account = doc.account && typeof doc.account === 'object' ? doc.account : {};
+    const fields = IDENTITY_FIELDS.flatMap((f) => {
+        const v = s(f === 'account.id' ? account.id : doc[f]);
+        return v ? [`${f}=${v}`] : [];
+    });
+    const type = s(doc.type) ?? s(doc.provider);
+    return type && fields.length ? JSON.stringify([type, ...fields]) : `file:${file}`;
+}
+/**
+ * After the hub has the logins: moves every auth file out of each directory a local CLIProxyAPI reads, into a sibling
+ * `<dir>.moved-to-shardflux` (0700; files keep their 0600), so a local copy started again has no tokens to refresh.
+ * Other files (a config.yaml, logs) stay where they are.
+ */
+export function moveAuthFilesAside(dirs, now = new Date()) {
+    const moved = [];
+    for (const dir of dirs) {
+        const files = authFiles(dir);
+        if (!files.length)
+            continue;
+        let to = `${dir}.moved-to-shardflux`;
+        if (existsSync(to))
+            to = `${to}-${now.toISOString().replace(/[-:]/g, '').slice(0, 15)}`;
+        mkdirSync(to, { recursive: true, mode: 0o700 });
+        chmodSync(to, 0o700);
+        for (const file of files) {
+            const target = join(to, file);
+            mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+            renameSync(join(dir, file), target);
+        }
+        moved.push({ from: dir, to, files: files.length });
+    }
+    return moved;
+}
+// ---- stopping it ---------------------------------------------------------------------------------------------------
+const shellWord = (s) => (/^[\w./:@%+=-]+$/.test(s) ? s : `'${s.replaceAll("'", `'\\''`)}'`);
+const shellLine = (argv) => argv.map(shellWord).join(' ');
+/** Whether something accepts connections on 127.0.0.1:port (also a listener on all interfaces). */
+export function portAnswers(port, host = '127.0.0.1') {
+    return new Promise((resolve) => {
+        const socket = connect({ port, host });
+        const done = (v) => { socket.destroy(); resolve(v); };
+        socket.setTimeout(1000, () => done(false));
+        socket.once('connect', () => done(true));
+        socket.once('error', () => done(false));
+    });
+}
+/**
+ * A Homebrew service: `brew services stop` (it also leaves login). Another launchd agent: bootout, disable, and its plist
+ * moved aside, so it cannot come back at login. A plain process: ending it.
+ */
+export function stopPlan(local, uid = userInfo().uid) {
+    const s = local.service;
+    if (s?.kind === 'brew')
+        return { line: shellLine(['brew', 'services', 'stop', s.formula]), steps: [{ run: ['brew', 'services', 'stop', s.formula] }] };
+    if (s?.kind === 'launchd') {
+        const target = `gui/${uid}/${s.label}`;
+        const aside = `${s.plist}.disabled-by-shardflux`;
+        const steps = [{ run: ['launchctl', 'bootout', target] }, { run: ['launchctl', 'disable', target] }, { move: [s.plist, aside] }];
+        return { line: `${shellLine(['launchctl', 'bootout', target])} && ${shellLine(['launchctl', 'disable', target])} && ${shellLine(['mv', s.plist, aside])}`, steps };
+    }
+    const l = local.listener;
+    // Only what is verified to be CLIProxyAPI is ever offered: a container by its image or name, a process by its executable.
+    if (l?.container?.cliProxy)
+        return { line: shellLine(['docker', 'stop', l.container.name]), steps: [{ run: ['docker', 'stop', l.container.name] }] };
+    if (l?.cliProxy)
+        return { line: shellLine(['kill', String(l.pid)]), steps: [{ kill: l.pid }] };
+    return null;
+}
+/** Why nothing is offered for what listens on the port, and what the user can do. */
+function unverified(local) {
+    const l = local.listener;
+    const port = local.port;
+    if (l?.container) {
+        return new UsageError(`Container ${l.container.name} (${l.container.image}) publishes 127.0.0.1:${port} and is not recognizably CLIProxyAPI, so it was left running.`, `if it is your CLIProxyAPI, run: ${shellLine(['docker', 'stop', l.container.name])} && ${AGAIN}`);
+    }
+    if (l)
+        return new UsageError(`${basename(l.executable) || 'A program'} (pid ${l.pid}) listens on 127.0.0.1:${port} and is not CLIProxyAPI, so it was left running.`, `stop it yourself if it is your CLIProxyAPI, then run: ${AGAIN}`);
+    return new UsageError(`Another program answers on 127.0.0.1:${port}.`, `stop the CLIProxyAPI that runs on this computer, then run: ${AGAIN}`);
+}
+const AGAIN = 'shard cli-proxy import';
+/**
+ * Stops the local CLIProxyAPI on its own port so only the hosted copy refreshes the logins. A Homebrew service is
+ * stopped with `brew services stop` (said first); a process or another launchd agent only with the user's consent
+ * ([Y/n] on a terminal, defaulting to yes; --yes otherwise): declined, the exact command is shown and the port is
+ * watched until it is free. Refuses when something starts it again.
+ */
+export async function stopLocalCliProxy(ctx, local, values = {}, deps = {}) {
+    const port = local.port;
+    const answers = deps.answers ?? cliProxyTools.answers;
+    const ours = deps.ours ?? (async () => (await cliProxyTools.identity(port)) !== null);
+    const run = deps.run ?? cliProxyTools.run;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const plan = stopPlan(local, deps.uid);
+    if (local.listener?.forwarder || !(await answers(port)) || (await ours()))
+        return { result: 'none', plan: null };
+    const l = local.listener;
+    if (!plan || (l && !l.cliProxy && !l.container?.cliProxy))
+        throw unverified(local);
+    const who = local.listener ? `pid ${local.listener.pid}` : local.service?.label ?? 'a local process';
+    const execute = async () => {
+        for (const step of plan.steps) {
+            if ('kill' in step)
+                (deps.kill ?? cliProxyTools.kill)(step.kill);
+            else if ('move' in step)
+                renameSync(step.move[0], step.move[1]);
+            else if ((await run(step.run[0], step.run.slice(1))) === null)
+                throw new UsageError(`Could not stop it (${shellLine(step.run)} failed).`, `run: ${plan.line} && ${AGAIN}`);
+        }
+    };
+    let stoppedByUs = false;
+    if (local.service?.kind === 'brew') {
+        progress(ctx, `Stopping your local CLIProxyAPI (${plan.line}) so only the hosted copy refreshes your logins…`);
+        await execute();
+        stoppedByUs = true;
+    }
+    else {
+        if (values.yes !== true && !ctx.input.interactive) {
+            throw new UsageError(`CLIProxyAPI still runs on this computer (${who}).`, `run: ${plan.line} && ${AGAIN} (or pass --yes)`);
+        }
+        let yes = values.yes === true;
+        if (!yes) {
+            const answer = (await ctx.input.answer(`CLIProxyAPI runs on this computer (${who}); only one copy may refresh your logins. Stop it now (${plan.line})? [Y/n] `))?.trim() ?? '';
+            yes = answer === '' || /^y(es)?$/i.test(answer);
+        }
+        if (yes) {
+            await execute();
+            stoppedByUs = true;
+        }
+        else {
+            progress(ctx, `Stop it yourself with: ${plan.line}\nWaiting for 127.0.0.1:${port} to be free (Ctrl-C to cancel)…`);
+        }
+    }
+    const deadline = Date.now() + (stoppedByUs ? 15_000 : (deps.waitMs ?? 300_000));
+    while (await answers(port)) {
+        ctx.signal.throwIfAborted();
+        if (Date.now() > deadline)
+            throw new UsageError(`CLIProxyAPI still answers on 127.0.0.1:${port}.`, `run: ${plan.line} && ${AGAIN}`);
+        await sleep(250);
+    }
+    // Something that starts it again (an app, a KeepAlive agent) would bring back a second copy.
+    await sleep(1500);
+    if (await answers(port)) {
+        throw new UsageError(`CLIProxyAPI started again on 127.0.0.1:${port}: an app or agent keeps it running.`, `quit that app or agent, then run: ${AGAIN}`);
+    }
+    return { result: 'stopped', plan };
+}
+/** How the user starts the local CLIProxyAPI again (`shard cli-proxy export` names it). */
+export function startLine(local, uid = userInfo().uid) {
+    const s = local.service;
+    if (s?.kind === 'brew')
+        return shellLine(['brew', 'services', 'start', s.formula]);
+    if (s?.kind === 'launchd') {
+        const target = `gui/${uid}/${s.label}`;
+        return `${shellLine(['mv', `${s.plist}.disabled-by-shardflux`, s.plist])} && ${shellLine(['launchctl', 'enable', target])} && ${shellLine(['launchctl', 'bootstrap', `gui/${uid}`, s.plist])}`;
+    }
+    const c = local.listener?.container;
+    if (c?.cliProxy)
+        return shellLine(['docker', 'start', c.name]);
+    if (local.listener?.cliProxy && local.listener.command)
+        return local.listener.command;
+    return local.configPath ? shellLine(['cli-proxy-api', '-config', local.configPath]) : 'cli-proxy-api';
+}
+// ---- the Mac forwarder (launchd) -----------------------------------------------------------------------------------
+const xml = (s) => s.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+/** The launchd agent: `shard cli-proxy forward` at login, started again whenever it exits. */
+export function forwarderPlist(o) {
+    const env = { SHARDFLUX_CONFIG_DIR: o.configDir, SHARDFLUX_API_URL: o.apiUrl, SHARDFLUX_NO_UPDATE_CHECK: '1', ...(o.path ? { PATH: o.path } : {}) };
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${FORWARD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${[o.node, o.script, 'cli-proxy', 'forward'].map((a) => `    <string>${xml(a)}</string>`).join('\n')}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${Object.entries(env).map(([k, v]) => `    <key>${k}</key>\n    <string>${xml(v)}</string>`).join('\n')}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>StandardOutPath</key>
+  <string>${xml(o.logFile)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(o.logFile)}</string>
+</dict>
+</plist>
+`;
+}
+export function forwarderPlistPath(home) {
+    return join(home, 'Library', 'LaunchAgents', `${FORWARD_LABEL}.plist`);
+}
+/** Whether Shardflux's forwarder (this computer's, or a VM's sf-agent) answers on 127.0.0.1:port, and for which hub. */
+export async function forwarderIdentity(port = CLI_PROXY_PORT) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}${IDENTITY_PATH}`, { signal: AbortSignal.timeout(2000) });
+        const body = (await res.json());
+        if (body.forwarder !== 'shardflux')
+            return null;
+        return { hub: typeof body.hub === 'string' ? body.hub : null, kind: body.kind === 'vm' ? 'vm' : 'mac', version: typeof body.version === 'string' ? body.version : null };
+    }
+    catch {
+        return null;
+    }
+}
+/** A Shardflux VM (its guest agent is installed): the hub is set up from the computer where CLIProxyAPI runs. */
+export function inShardfluxVm() {
+    return existsSync('/usr/local/sbin/sf-guest-agent') || existsSync('/run/sf-guest-agent');
+}
+/** The forwarder that answers is this shard's (an update replaces the program, not the running process). */
+const current = (id) => id !== null && id.kind === 'mac' && id.version === CLI_VERSION;
+/** The shard version the launchd forwarder runs (refreshForwarderAgent compares it with this one). */
+function recordForwarder(dir) {
+    new AgentStateStore(dir).update((doc) => { doc.cli_proxy_forwarder = { version: CLI_VERSION }; });
+}
+/**
+ * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
+ * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
+ * one. Returns whether it was.
+ */
+export async function refreshForwarderAgent(env, dir, deps = {}) {
+    if ((deps.platform ?? process.platform) !== 'darwin')
+        return false;
+    if (!existsSync(forwarderPlistPath(env.HOME || homedir())))
+        return false;
+    const store = new AgentStateStore(dir);
+    const record = store.read().cli_proxy_forwarder;
+    if (record?.version === CLI_VERSION)
+        return false;
+    // Recorded first: a failed restart is not retried on every command (the next import installs the agent again).
+    recordForwarder(dir);
+    await (deps.run ?? cliProxyTools.run)('launchctl', ['kickstart', '-k', `gui/${deps.uid ?? userInfo().uid}/${FORWARD_LABEL}`]);
+    return true;
+}
+/** Installs (or refreshes) the launchd agent and waits until the forwarder answers. macOS only. */
+export async function installForwarderAgent(ctx, apiUrl, deps = {}) {
+    const runtime = ctx.runtime;
+    if (!runtime)
+        throw new UsageError('The forwarder needs an installed shard.', `run: npm i -g shardflux && ${AGAIN}`);
+    let script = runtime.script;
+    try {
+        script = realpathSync(script);
+    }
+    catch { /* keep the path */ }
+    if (/[\\/]_npx[\\/]/.test(script))
+        throw new UsageError('The forwarder needs an installed shard (npx removes its copy).', `run: npm i -g shardflux && ${AGAIN}`);
+    const home = ctx.io.env.HOME || homedir();
+    const file = forwarderPlistPath(home);
+    const text = forwarderPlist({ node: runtime.node, script, configDir: ctx.store.dir, apiUrl, logFile: join(ctx.store.dir, 'cli-proxy-forward.log'), ...(ctx.io.env.PATH ? { path: ctx.io.env.PATH } : {}) });
+    const run = deps.run ?? cliProxyTools.run;
+    const domain = `gui/${deps.uid ?? userInfo().uid}`;
+    let installed = null;
+    try {
+        installed = readFileSync(file, 'utf8');
+    }
+    catch { /* first install */ }
+    const identity = deps.identity ?? (() => cliProxyTools.identity());
+    if (installed === text && current(await identity())) {
+        recordForwarder(ctx.store.dir);
+        return file;
+    }
+    mkdirSync(join(home, 'Library', 'LaunchAgents'), { recursive: true });
+    writeFileSync(file, text, { mode: 0o644 });
+    await run('launchctl', ['bootout', `${domain}/${FORWARD_LABEL}`]);
+    if ((await run('launchctl', ['bootstrap', domain, file])) === null) {
+        throw new UsageError('Could not start the forwarder.', `run: launchctl bootstrap ${domain} ${shellWord(file)}`);
+    }
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let i = 0; i < 40; i++) {
+        if (current(await identity())) {
+            recordForwarder(ctx.store.dir);
+            return file;
+        }
+        await sleep(250);
+    }
+    throw new UsageError('The forwarder did not answer on 127.0.0.1:8317.', `see: tail ${shellWord(join(ctx.store.dir, 'cli-proxy-forward.log'))}`);
+}
+// ---- the machine template ------------------------------------------------------------------------------------------
+const digest = (text) => createHash('sha256').update(text).digest('hex');
+/**
+ * Puts the hub info into the machine template (opening the machine VM like `shard machine`, then saving it), so every
+ * new VM's forwarder reaches the hub. Skipped when the saved machine already carries this hub info.
+ */
+export async function saveHubInfoToMachine(ctx, info, opts = {}) {
+    // VMs get what their forwarder needs (the callback URL), never the management key. `current` reads the hub's
+    // stored callback again (under its lock), so a URL another device replaced is never what VMs receive.
+    const latest = opts.current ?? (() => Promise.resolve(info));
+    const vmText = async () => {
+        const t = vmHubInfoText(await latest());
+        if (!t)
+            throw new HubError('The hub’s VM address comes with its next update.', `then connect your VMs: ${AGAIN}`);
+        return t;
+    };
+    let text = await vmText();
+    const store = new AgentStateStore(ctx.store.dir);
+    const record = store.read().cli_proxy_machine;
+    const machine = opts.machine ?? sdkMachine(ctx);
+    const current = await machine.version();
+    // The record names the file too: a machine saved with the earlier path gets the hub info where VMs read it now.
+    if (record?.hash === digest(VM_HUB_INFO_PATH + '\n' + text) && record.api_url === ctx.apiUrl && typeof record.version === 'number' && current >= record.version)
+        return { version: record.version, saved: false };
+    progress(ctx, 'Adding the hub to your machine, so every new VM reaches it…');
+    const vm = await machine.open();
+    // Opening the machine VM takes a while: what is written is the callback that is valid now.
+    text = await vmText();
+    const hash = digest(VM_HUB_INFO_PATH + '\n' + text);
+    await vm.write(VM_HUB_INFO_PATH, text);
+    const version = await vm.save();
+    store.update((doc) => { doc.cli_proxy_machine = { hash, version, api_url: ctx.apiUrl }; });
+    return { version, saved: true };
+}
+/**
+ * The hub's home: the organization's first project (oldest), listed with the user session. Null when signed out, so a
+ * new hub is never created by guesswork in another project.
+ */
+export async function homeProject(ctx, organizationId) {
+    if (ctx.sessionSource() === null)
+        return null;
+    const all = [];
+    for await (const p of ctx.account().projects.listAll(organizationId))
+        all.push(p);
+    all.sort((a, b) => a.created_at.localeCompare(b.created_at) || a.id.localeCompare(b.id));
+    return all[0] ? { id: all[0].id, slug: all[0].slug } : null;
+}
+export function sdkMachine(ctx) {
+    const cloud = ctx.cloud();
+    return {
+        version: async () => (await cloud.machine.get({ signal: ctx.signal })).version,
+        async open() {
+            const state = await cloud.machine.get({ signal: ctx.signal });
+            const key = `machine/${state.organization_id}/v${state.version}`;
+            const existing = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
+            const ws = await cloud.workspaces.open({
+                key, template: state.template ? `${state.template.slug}@${state.template.version}` : 'coding',
+                labels: { ...existing?.labels, shard_layer: 'machine', shard_machine: state.organization_id, repo_path: '/home/user', app: 'claude', agent: 'machine' },
+                wait: { timeoutMs: Math.max(ctx.wakeTimeoutMs, 180_000), signal: ctx.signal },
+            });
+            if (state.version === 0)
+                await syncAgentConfig(ctx, ws);
+            const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+            return {
+                write: async (path, text) => { await cell.files.write(path, text, { mode: '0600', createParents: true }); },
+                save: async () => { const saved = await cloud.machine.save({ workspaceId: ws.id }, { signal: ctx.signal }); return saved.pending?.version ?? saved.version; },
+            };
+        },
+    };
+}
+/** The hub's logins from its management API (wakes the hub). */
+export async function hubAccounts(info, timeoutMs = 45_000) {
+    const res = await fetch(new URL('v0/management/auth-files', info.callback_url), {
+        headers: { authorization: `Bearer ${info.management_key}`, accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) {
+        const reason = res.headers.get('x-shardflux-reason');
+        throw new HubError(`The hub did not list its accounts (HTTP ${res.status}${reason ? `, ${reason}` : ''})`);
+    }
+    const body = (await res.json());
+    return (body.files ?? []).map((f) => ({
+        provider: [f.provider, f.type].find((v) => typeof v === 'string' && v !== '') ?? 'unknown',
+        email: typeof f.email === 'string' && f.email ? f.email : null,
+        status: typeof f.status === 'string' && f.status ? f.status : null,
+        disabled: f.disabled === true,
+    }));
+}
+/** Whether the hub answers /healthz through its callback URL, and the edge's reason when it does not. */
+export async function hubHealth(info, timeoutMs = 45_000) {
+    try {
+        const res = await fetch(new URL('healthz', info.callback_url), { signal: AbortSignal.timeout(timeoutMs) });
+        await res.arrayBuffer().catch(() => undefined);
+        return { ok: res.ok, reason: res.headers.get('x-shardflux-reason') ?? (res.ok ? null : `HTTP ${res.status}`) };
+    }
+    catch (err) {
+        return { ok: false, reason: err.name === 'TimeoutError' ? 'timeout' : 'unreachable' };
+    }
+}
+const accountLine = (a) => `  ${a.provider.padEnd(8)} ${a.email ?? '(no email)'}${a.disabled ? '  disabled' : a.status && a.status !== 'active' ? `  ${a.status}` : ''}`;
+/**
+ * Moves CLIProxyAPI from this computer into the account (or connects this computer to the account's hub): ensure the
+ * hub from the user's config, stop the local copy, upload the auth files the hub does not have yet (never overwriting
+ * one: the hub's copy may hold a newer refresh token), start the forwarder on 127.0.0.1:8317 and put the hub info into
+ * the machine template.
+ */
+export async function importCliProxy(ctx, opts = {}) {
+    if (cliProxyTools.inVm()) {
+        throw new UsageError('shard cli-proxy import runs on the computer where CLIProxyAPI runs; this is a Shardflux VM, which reaches the hub at http://127.0.0.1:8317 already.', 'run it on the computer where cli-proxy runs: shard cli-proxy import');
+    }
+    const values = opts.values ?? {};
+    const platform = opts.platform ?? process.platform;
+    const local = opts.local !== undefined ? opts.local : await detectLocalCliProxy({ env: ctx.io.env, ...(typeof values.config === 'string' ? { configPath: values.config } : {}) });
+    const hub = opts.hub ?? sdkHubCloud(ctx.cloud(), { signal: ctx.signal, wakeTimeoutMs: ctx.wakeTimeoutMs, agentLabel: ctx.agentLabel, homeProject: (org) => homeProject(ctx, org) });
+    const known = readHubInfo(ctx.store.dir, ctx.apiUrl);
+    if (!local?.logins.length && !known && !(await hub.open(false))) {
+        throw new UsageError(`No CLIProxyAPI logins on this computer (looked in ${local?.authDir ?? '~/.cli-proxy-api'}).`, 'name the config of yours: shard cli-proxy import --config <path>');
+    }
+    const userConfig = local?.configPath ? readFileSync(local.configPath, 'utf8') : undefined;
+    const ensured = await ensureCliProxyHub(hub, { dir: ctx.store.dir, apiUrl: ctx.apiUrl, ...(userConfig !== undefined ? { userConfig } : {}), progress: (m) => progress(ctx, m) });
+    for (const value of [ensured.info.callback_url, ensured.info.management_key])
+        ctx.addSecret(value);
+    // The forwarder takes 127.0.0.1:8317: refuse before stopping anything when another program holds it.
+    if (local && local.port !== CLI_PROXY_PORT) {
+        const answers = opts.stop?.answers ?? cliProxyTools.answers;
+        const ours = opts.stop?.ours ?? (async () => (await cliProxyTools.identity(CLI_PROXY_PORT)) !== null);
+        if ((await answers(CLI_PROXY_PORT)) && !(await ours())) {
+            throw new UsageError(`Another program answers on 127.0.0.1:${CLI_PROXY_PORT}, where this computer’s forwarder listens; nothing was changed.`, `stop it, then run: ${AGAIN}`);
+        }
+    }
+    const stop = local ? await stopLocalCliProxy(ctx, local, values, opts.stop) : { result: 'none', plan: null };
+    // Auth files: read after the local copy stopped (its last refresh is in them), uploaded only when the hub has none.
+    const uploaded = [], kept = [];
+    const added = [], already = [];
+    let movedAside = [];
+    if (local?.logins.length) {
+        const opened = await hub.open(false);
+        if (!opened)
+            throw new HubError('The hub was deleted during the import.', `run: ${AGAIN}`);
+        // Only accounts the hub does not have: compared by identity (provider type + email or account id, read from each
+        // auth file's JSON, the hub's and this computer's), under the hub's logins lock, so two computers importing at
+        // once never add one account twice and an account the hub holds keeps its newer tokens, whatever the file names.
+        await opened.ws.withLock('logins', async () => {
+            const inHub = new Set();
+            const present = await opened.ws.authFiles();
+            for (const rel of present) {
+                const text = await opened.ws.read(`${HUB_AUTH_DIR}/${rel}`);
+                inHub.add(text === null ? `file:${rel}` : loginIdentity(text, rel));
+            }
+            const names = new Set(present);
+            for (const login of local.logins) {
+                const text = readFileSync(join(local.authDir, login.file), 'utf8');
+                const account = loginIdentity(text, login.file);
+                const r = inHub.has(account) || names.has(login.file) ? null : await opened.ws.sh(ADD_AUTH_SCRIPT, [login.file], { stdin: text });
+                if (r && r.code !== 0)
+                    throw new HubError(`Could not add ${login.file} to the hub: ${r.stderr.trim().split('\n').at(-1) || `exit ${r.code}`}`, `run: ${AGAIN}`);
+                if (!r || r.stdout.trim() === 'exists') {
+                    kept.push(login.file);
+                    already.push({ provider: login.provider, email: login.email });
+                    continue;
+                }
+                uploaded.push(login.file);
+                added.push({ provider: login.provider, email: login.email });
+                inHub.add(account);
+                names.add(login.file);
+            }
+        });
+        if (uploaded.length)
+            progress(ctx, `Moved ${uploaded.length} login${uploaded.length === 1 ? '' : 's'} to the hub`);
+        // The hub holds every login now: no local copy keeps tokens it could refresh.
+        movedAside = moveAuthFilesAside(local.authDirs);
+    }
+    if (local) {
+        new AgentStateStore(ctx.store.dir).update((doc) => {
+            doc.cli_proxy_local = { api_url: ctx.apiUrl, auth_dir: local.authDir, port: local.port, config: local.configPath, service: local.service, stopped: stop.plan?.line ?? null, start: startLine(local), moved: movedAside };
+        });
+    }
+    let launchd = null;
+    if (platform === 'darwin' && opts.launchd !== false)
+        launchd = await installForwarderAgent(ctx, ctx.apiUrl, opts.launchd || {});
+    // Everything above already works for this computer; the machine step is reported, never undone by its failure.
+    let machine = null;
+    if (opts.machine !== false) {
+        const current = async () => {
+            const opened = await hub.open(false);
+            if (!opened)
+                throw new HubError('The hub was deleted during the import.', `run: ${AGAIN}`);
+            if (!ensured.info.vm_callback_url)
+                return ensured.info;
+            // What VMs get is the VM port's URL, read again under the hub's lock right before it is written.
+            const vm = (await hubCallback(opened.ws, false, CLI_PROXY_VM_PORT)).callback;
+            const info = { ...ensured.info, vm_callback_url: vm.callback_url, vm_callback_created_at: vm.callback_created_at };
+            if (info.vm_callback_url !== ensured.info.vm_callback_url)
+                writeHubInfo(ctx.store.dir, info);
+            return info;
+        };
+        try {
+            machine = await saveHubInfoToMachine(ctx, ensured.info, { current });
+        }
+        catch (err) {
+            machine = { error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    const accounts = await hubAccounts(ensured.info).catch(() => null);
+    return {
+        hub: { workspace_id: ensured.info.workspace_id, created: ensured.created, process: ensured.process },
+        logins: { uploaded, kept, added, already, moved_aside: movedAside.map((m) => m.to) }, config: ensured.config ? 'from_this_computer' : 'kept', local: stop.result, port: local?.port ?? CLI_PROXY_PORT, forwarder: { launchd }, machine, dropped: ensured.config?.dropped ?? [], accounts,
+    };
+}
+/**
+ * Brings the hub's logins back to this computer: the hub stops first (from then on only this computer refreshes
+ * them), its auth files as last refreshed are written to the local auth directory (0600), the hub sets its copies
+ * aside (a later import uploads this computer's), this computer's forwarder agent goes, and the hub is suspended.
+ * Undone by `shard cli-proxy import`.
+ */
+export async function exportCliProxy(ctx, opts = {}) {
+    if (cliProxyTools.inVm())
+        throw new UsageError('shard cli-proxy export runs on the computer that should hold your logins, not in a VM.', 'run it on that computer: shard cli-proxy export');
+    const values = opts.values ?? {};
+    const info = readHubInfo(ctx.store.dir, ctx.apiUrl);
+    if (!info)
+        throw new UsageError('This computer is not connected to a hosted CLIProxyAPI.', `to move yours into your account: ${AGAIN}`);
+    for (const value of [info.callback_url, info.management_key])
+        ctx.addSecret(value);
+    if (values.yes !== true) {
+        if (!ctx.input.interactive)
+            throw new UsageError('Export stops the hosted CLIProxyAPI for every device and VM and brings its logins to this computer.', 'run: shard cli-proxy export --yes');
+        const answer = (await ctx.input.answer('Bring your logins back to this computer and stop the hosted CLIProxyAPI for every device and VM? [Y/n] '))?.trim() ?? '';
+        if (!(answer === '' || /^y(es)?$/i.test(answer)))
+            throw new UsageError('Nothing was changed.');
+    }
+    const hub = opts.hub ?? sdkHubCloud(ctx.cloud(), { signal: ctx.signal, wakeTimeoutMs: ctx.wakeTimeoutMs, agentLabel: ctx.agentLabel });
+    const opened = await hub.open(false);
+    if (!opened)
+        throw new HubError('The hosted CLIProxyAPI no longer exists.', 'nothing to bring back');
+    progress(ctx, 'Stopping the hosted CLIProxyAPI…');
+    const stopped = await opened.ws.sh(STOP_SCRIPT, [], { timeoutMs: 120_000 });
+    if (stopped.code !== 0 || !stopped.stdout.includes('stopped')) {
+        throw new HubError(`The hosted CLIProxyAPI did not stop: ${stopped.stderr.trim().split('\n').at(-1) || `exit ${stopped.code}`}`, 'run: shard cli-proxy export --yes');
+    }
+    const store = new AgentStateStore(ctx.store.dir);
+    const record = store.read().cli_proxy_local;
+    const mine = record?.api_url === ctx.apiUrl ? record : undefined;
+    const home = ctx.io.env.HOME || homedir();
+    const authDir = typeof mine?.auth_dir === 'string' ? mine.auth_dir : join(home, '.cli-proxy-api');
+    mkdirSync(authDir, { recursive: true, mode: 0o700 });
+    const logins = [];
+    for (const rel of await opened.ws.authFiles()) {
+        const text = await opened.ws.read(`${HUB_AUTH_DIR}/${rel}`);
+        if (text === null)
+            continue;
+        const target = join(authDir, rel);
+        mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+        writeFileSync(target, text, { mode: 0o600 });
+        chmodSync(target, 0o600);
+        logins.push(rel);
+    }
+    const aside = await opened.ws.sh(SET_ASIDE_SCRIPT);
+    if (aside.code !== 0)
+        throw new HubError('The hub did not set its logins aside.', 'run: shard cli-proxy export --yes');
+    let removed = false;
+    if ((opts.platform ?? process.platform) === 'darwin' && opts.launchd !== false) {
+        await removeForwarderAgent(home, opts.launchd?.run ?? cliProxyTools.run, opts.launchd?.uid);
+        removed = true;
+    }
+    await hub.suspend(opened.ws.id).catch(() => undefined);
+    store.update((doc) => { doc.cli_proxy_exported = { api_url: ctx.apiUrl, at: new Date().toISOString(), auth_dir: authDir }; });
+    return {
+        auth_dir: authDir, logins, hub: { workspace_id: opened.ws.id, state: 'stopped', logins_set_aside: aside.stdout.trim() || null },
+        forwarder: { removed }, start: typeof mine?.start === 'string' && mine.start ? mine.start : 'cli-proxy-api',
+    };
+}
+async function exportHandler(ctx, values) {
+    const r = await exportCliProxy(ctx, { values });
+    if (ctx.json) {
+        ctx.io.stdout.write(json(r));
+        return 0;
+    }
+    ctx.io.stdout.write([
+        `Your logins are on this computer again: ${r.logins.length} in ${r.auth_dir}.`,
+        `The hosted CLIProxyAPI is stopped${r.forwarder.removed ? ', and this computer no longer forwards 127.0.0.1:8317' : ''}.`,
+        `Start your local CLIProxyAPI: ${r.start}`,
+        `Move it back into your account any time: ${AGAIN}`,
+    ].join('\n') + '\n');
+    return 0;
+}
+// ---- handlers ------------------------------------------------------------------------------------------------------
+function statusLines(state, accounts, forwarding, launchd, machineVersion) {
+    const hub = state === null ? 'missing (run shard cli-proxy import)' : state === 'running' ? 'running' : ['suspended', 'parked', 'stopped'].includes(state) ? 'sleeping (wakes on the next request)' : state;
+    const lines = [`CLIProxyAPI hub: ${hub} · ${HUB_KEY}`];
+    if (accounts)
+        lines.push(`Accounts: ${accounts.length}`, ...accounts.map(accountLine));
+    lines.push(`This computer: ${forwarding ? `http://127.0.0.1:${CLI_PROXY_PORT}${launchd ? ` (launchd ${FORWARD_LABEL})` : ''}` : `not forwarding; connect it: shard cli-proxy import`}`);
+    lines.push(`VMs: ${machineVersion !== null ? `every new VM reaches it at http://127.0.0.1:${CLI_PROXY_PORT} (machine version ${machineVersion})` : 'run shard cli-proxy import to add the hub to your machine'}`);
+    return `${lines.join('\n')}\n`;
+}
+async function status(ctx, values) {
+    if (cliProxyTools.inVm()) {
+        // In a VM: sf-agent forwards 127.0.0.1:8317 to the hub; the hub is managed from the computer that set it up.
+        const identity = await cliProxyTools.identity();
+        const forwarding = identity?.kind === 'vm' ? identity : null;
+        if (ctx.json) {
+            ctx.io.stdout.write(json({ vm: true, forwarder: forwarding ? { kind: 'vm', hub: forwarding.hub, version: forwarding.version } : null }));
+            return 0;
+        }
+        ctx.io.stdout.write(forwarding
+            ? `This VM reaches your account’s hosted CLIProxyAPI at http://127.0.0.1:${CLI_PROXY_PORT} (sf-agent forwarder${forwarding.version ? ` ${forwarding.version}` : ''}).\nIts logins and settings are managed from the computer that set it up: shard cli-proxy\n`
+            : `This VM has no hosted CLIProxyAPI yet. Set it up on the computer where CLIProxyAPI runs: shard cli-proxy import\n`);
+        return 0;
+    }
+    let info = readHubInfo(ctx.store.dir, ctx.apiUrl);
+    if (!info) {
+        const local = await detectLocalCliProxy({ env: ctx.io.env, ...(typeof values.config === 'string' ? { configPath: values.config } : {}) }).catch(() => null);
+        const found = local?.logins.length ? local.logins : [];
+        if (ctx.json) {
+            ctx.io.stdout.write(json({ hub: null, local: local ? { auth_dir: local.authDir, logins: found.map(({ provider, email }) => ({ provider, email })), config: local.configPath } : null }));
+            return 0;
+        }
+        ctx.io.stdout.write(found.length
+            ? `CLIProxyAPI on this computer: ${found.length} login${found.length === 1 ? '' : 's'} (${found.map((l) => `${l.provider ?? 'unknown'} ${l.email ?? ''}`.trim()).join(', ')}).\nMove it to your account, so every device and VM uses one copy at http://127.0.0.1:${CLI_PROXY_PORT}: shard cli-proxy import\n`
+            : `No hosted CLIProxyAPI yet. Run CLIProxyAPI on this computer, then: shard cli-proxy import\n`);
+        return 0;
+    }
+    for (const value of [info.callback_url, info.management_key])
+        ctx.addSecret(value);
+    const hub = sdkHubCloud(ctx.cloud(), { signal: ctx.signal, wakeTimeoutMs: ctx.wakeTimeoutMs, agentLabel: ctx.agentLabel });
+    const state = await hub.state(info.workspace_id);
+    let accounts = null;
+    let repaired = false;
+    let renewed = false;
+    let note = null;
+    if (state !== null) {
+        let health = await hubHealth(info);
+        if (!health.ok && health.reason === 'callback_invalid') {
+            // The API key that created the hub's address was revoked: a new address for every device and VM.
+            try {
+                progress(ctx, 'Renewing the hub’s address…');
+                const r = await renewHubCallbacks(ctx, { hub });
+                info = r.info;
+                renewed = true;
+                const v = await r.vms;
+                note = v.machine !== null
+                    ? `The hub has a new address (the API key that created the old one was revoked); VMs get it with machine version ${v.machine}.`
+                    : `The hub has a new address (the API key that created the old one was revoked). VMs: ${v.note ?? 'not updated'}; run: ${AGAIN}`;
+                health = await hubHealth(info);
+            }
+            catch (err) {
+                if (!(err instanceof HubError))
+                    throw err;
+                note = `${err.message}${err.hint ? ` (${err.hint})` : ''}`;
+            }
+        }
+        if (!health.ok && health.reason === 'port_not_listening') {
+            try {
+                progress(ctx, 'Starting CLIProxyAPI in the hub again…');
+                await ensureCliProxyHub(hub, { dir: ctx.store.dir, apiUrl: ctx.apiUrl, repairOnly: true });
+                repaired = true;
+                health = await hubHealth(info);
+            }
+            catch (err) {
+                if (!(err instanceof HubError))
+                    throw err;
+                note = `${err.message}${err.hint ? ` (${err.hint})` : ''}`;
+            }
+        }
+        if (health.ok)
+            accounts = await hubAccounts(info).catch(() => null);
+    }
+    const identity = await cliProxyTools.identity();
+    const launchd = existsSync(forwarderPlistPath(ctx.io.env.HOME || homedir()));
+    const record = new AgentStateStore(ctx.store.dir).read().cli_proxy_machine;
+    const machineVersion = record?.api_url === ctx.apiUrl && typeof record.version === 'number' ? record.version : null;
+    const forwarding = identity?.hub === info.workspace_id;
+    if (ctx.json) {
+        ctx.io.stdout.write(json({ hub: { workspace_id: info.workspace_id, key: HUB_KEY, state, restarted: repaired, renewed, note }, accounts, forwarder: { local: forwarding, launchd }, machine: machineVersion === null ? null : { version: machineVersion } }));
+        return 0;
+    }
+    ctx.io.stdout.write(statusLines(state, accounts, forwarding, launchd, machineVersion) + (note ? `${note}\n` : ''));
+    return 0;
+}
+const accountName = (a) => [a.provider ?? 'login', a.email].filter(Boolean).join(' ');
+async function importHandler(ctx, values) {
+    const r = await importCliProxy(ctx, { values });
+    if (ctx.json) {
+        ctx.io.stdout.write(json(r));
+        return 0;
+    }
+    const lines = [
+        `CLIProxyAPI runs in your account (${HUB_KEY}); it sleeps between requests and wakes on the next one.`,
+        ...(r.logins.added.length ? [`Added to the hub: ${r.logins.added.map(accountName).join(', ')}.`] : []),
+        ...(r.logins.already.length ? [`Already in the hub (its sign-ins stay): ${r.logins.already.map(accountName).join(', ')}.`] : []),
+        ...(r.config === 'kept' ? ['The hub keeps its settings (client keys, routing, upstream keys).'] : []),
+        ...r.logins.moved_aside.map((dir) => `This computer’s auth files are in ${dir} now, where no CLIProxyAPI reads them.`),
+        ...(r.port !== CLI_PROXY_PORT ? [`Point tools that used http://127.0.0.1:${r.port} at http://127.0.0.1:${CLI_PROXY_PORT}.`] : []),
+        ...(r.accounts ? [`Accounts: ${r.accounts.length}`, ...r.accounts.map(accountLine)] : []),
+        r.forwarder.launchd ? `This computer: http://127.0.0.1:${CLI_PROXY_PORT} forwards to it (starts at login).` : `This computer: run shard cli-proxy forward to reach it at http://127.0.0.1:${CLI_PROXY_PORT}.`,
+        r.machine && 'version' in r.machine ? `VMs: every new VM reaches it at http://127.0.0.1:${CLI_PROXY_PORT} (machine version ${r.machine.version}).` : '',
+        r.machine && 'error' in r.machine ? `VMs: ${r.machine.error} Connect them with: ${AGAIN}` : '',
+        ...(r.dropped.length ? [`Kept on this computer only: ${r.dropped.join('; ')}.`] : []),
+        'Claude Code, Codex and T3 Code keep their settings.',
+    ].filter(Boolean);
+    ctx.io.stdout.write(`${lines.join('\n')}\n`);
+    return 0;
+}
+async function forwardHandler(ctx) {
+    const source = hubInfoSource(ctx.store.dir);
+    const log = (line) => void ctx.io.stderr.write(`${new Date().toISOString()} ${line}\n`);
+    const forwarder = new CliProxyForwarder({
+        hub: source,
+        log,
+        repair: async () => {
+            const info = source();
+            if (!info || info.api_url !== ctx.apiUrl)
+                throw new Error('the hub belongs to another API URL');
+            await ensureCliProxyHub(sdkHubCloud(ctx.cloud(), { signal: ctx.signal, wakeTimeoutMs: ctx.wakeTimeoutMs, agentLabel: ctx.agentLabel }), { dir: ctx.store.dir, apiUrl: info.api_url, repairOnly: true });
+        },
+        renew: async () => {
+            const info = source();
+            if (!info || info.api_url !== ctx.apiUrl)
+                throw new Error('the hub belongs to another API URL');
+            const r = await renewHubCallbacks(ctx);
+            void r.vms.then((v) => log(v.machine !== null ? `VMs get the hub’s new address with machine version ${v.machine}` : `VMs: ${v.note ?? 'not updated'}; run: ${AGAIN}`));
+        },
+    });
+    if (!source())
+        log('not connected to a hosted CLIProxyAPI yet; answering 503 until shard cli-proxy import connects this computer');
+    await forwarder.listen();
+    await new Promise((resolve) => {
+        if (ctx.signal.aborted)
+            return resolve();
+        ctx.signal.addEventListener('abort', () => resolve(), { once: true });
+    });
+    await forwarder.close();
+    return 0;
+}
+/**
+ * After the edge refused the hub's callback URL (`callback_invalid`: the API key that created it was revoked):
+ * replaces the URLs the edge refuses (under the hub's lock), saves them locally and gives VMs the new VM address.
+ */
+export async function renewHubCallbacks(ctx, opts = {}) {
+    const hub = opts.hub ?? sdkHubCloud(ctx.cloud(), { signal: ctx.signal, wakeTimeoutMs: ctx.wakeTimeoutMs, agentLabel: ctx.agentLabel });
+    const r = await ensureCliProxyHub(hub, { dir: ctx.store.dir, apiUrl: ctx.apiUrl, repairOnly: true, renewInvalid: true });
+    for (const v of [r.info.callback_url, r.info.vm_callback_url ?? ''])
+        if (v)
+            ctx.addSecret(v);
+    // This computer uses the new address at once; the machine (VMs) follows.
+    const vms = saveHubInfoToMachine(ctx, r.info, opts.machine ? { machine: opts.machine } : {}).then((saved) => ({ machine: saved.version, note: null }), (err) => ({ machine: null, note: err instanceof Error ? err.message : String(err) }));
+    return { info: r.info, vms };
+}
+/** Removes the launchd agent (tests and a future `shard cli-proxy forward --stop`). */
+export async function removeForwarderAgent(home, run = runProgram, uid = userInfo().uid) {
+    await run('launchctl', ['bootout', `gui/${uid}/${FORWARD_LABEL}`]);
+    rmSync(forwarderPlistPath(home), { force: true });
+}
+export const CLI_PROXY_HANDLERS = {
+    'cli-proxy': status,
+    'cli-proxy import': importHandler,
+    'cli-proxy export': exportHandler,
+    'cli-proxy forward': forwardHandler,
+};