@shardflux/cli 0.20.0 → 0.22.0

package/dist/cli-proxy.js

@@ -1,15 +1,18 @@
 /**
- * `shard cli-proxy` (status), `shard cli-proxy import` and the hidden `shard cli-proxy forward`: one hosted
+ * `shard cli-proxy` (status), `shard cli-proxy import`, `shard cli-proxy use` 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)`.
+ *
+ * One login per provider serves requests (the user's active one, `shard cli-proxy use` switches it); the provider's
+ * other logins stay in the hub, disabled, so CLIProxyAPI never moves a request to another account by itself.
  */
 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 { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { connect } from 'node:net';
 import { homedir, userInfo } from 'node:os';
 import { basename, dirname, join } from 'node:path';
@@ -18,9 +21,9 @@ 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 { ADD_AUTH_SCRIPT, CLI_PROXY_PORT, CLI_PROXY_VM_PORT, HUB_ACTIVE_FILE, HUB_AUTH_DIR, HUB_KEY, HubError, SET_ASIDE_SCRIPT, STOP_SCRIPT, enforceActiveLogins, enforceHubLoginsIfRunning, ensureCliProxyHub, hubCallback, listHubLogins, parseActive, readHubInfo, sdkHubCloud, vmHubInfoText, withDisabled, writeHubInfo } from "./cli-proxy-hub.js";
 import { CLI_VERSION } from "./args.js";
-import { UsageError } from "./errors.js";
+import { UsageError, describeError } from "./errors.js";
 import { json } from "./format.js";
 import { progress } from "./progress.js";
 const execute = promisify(execFile);
@@ -625,6 +628,20 @@ export function sdkMachine(ctx) {
         },
     };
 }
+/** The auth file a management API entry names, relative to the hub's auth directory. */
+function entryFile(f) {
+    if (typeof f.path === 'string' && f.path.startsWith(`${HUB_AUTH_DIR}/`))
+        return f.path.slice(HUB_AUTH_DIR.length + 1);
+    return [f.id, f.name].find((v) => typeof v === 'string' && v !== '') ?? null;
+}
+/**
+ * Marks each provider's active login: an enabled login whose file is one of `activeFiles` (the hub's active.json).
+ * Without them (unreadable), a provider's only enabled login is its active one.
+ */
+export function markActive(accounts, activeFiles) {
+    const enabled = (p) => accounts.filter((a) => a.provider === p && !a.disabled).length;
+    return accounts.map((a) => ({ ...a, active: !a.disabled && (activeFiles ? a.file !== null && activeFiles.has(a.file) : enabled(a.provider) === 1) }));
+}
 /** 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), {
@@ -640,6 +657,8 @@ export async function hubAccounts(info, timeoutMs = 45_000) {
         email: typeof f.email === 'string' && f.email ? f.email : null,
         status: typeof f.status === 'string' && f.status ? f.status : null,
         disabled: f.disabled === true,
+        file: entryFile(f),
+        active: false,
     }));
 }
 /** Whether the hub answers /healthz through its callback URL, and the edge's reason when it does not. */
@@ -653,12 +672,71 @@ export async function hubHealth(info, timeoutMs = 45_000) {
         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}` : ''}`;
+const accountLine = (a) => `  ${a.provider.padEnd(8)} ${a.email ?? '(no email)'}${a.active ? '  active' : ''}${a.disabled ? '  disabled' : a.status && a.status !== 'active' ? `  ${a.status}` : ''}`;
+/** The logins a `--use` or `shard cli-proxy use` value names: by email (any case), path in the auth folder, or file name. */
+export function matchLogins(spec, logins) {
+    const want = spec.trim().toLowerCase();
+    return logins.filter((l) => l.provider !== null && want !== '' && (l.email?.toLowerCase() === want || l.file.toLowerCase() === want || basename(l.file).toLowerCase() === want));
+}
+const loginName = (l) => l.email ?? l.file;
+const refs = (logins, active) => logins.filter((l) => l.provider !== null && l.active === active).map((l) => ({ provider: l.provider, email: l.email, file: l.file }));
+/**
+ * Resolves `--use` (repeatable): each value names one login per provider, on this computer or already in the hub.
+ * Checked before anything changes, so a typo stops the import with the logins to pick from.
+ */
+function resolveUse(specs, local, hub) {
+    const out = new Map();
+    const localLogins = (local?.logins ?? []).map((l) => {
+        let text = '';
+        try {
+            text = readFileSync(join(local.authDir, l.file), 'utf8');
+        }
+        catch { /* unreadable: matched by name only */ }
+        return { ...l, identity: loginIdentity(text, l.file) };
+    });
+    const by = new Map();
+    for (const spec of specs) {
+        const mineHere = matchLogins(spec, localLogins), inHub = matchLogins(spec, hub);
+        if (!mineHere.length && !inHub.length) {
+            const all = [...localLogins.filter((l) => l.provider), ...hub.filter((l) => l.provider)].map((l) => `${l.provider} ${loginName(l)}`);
+            throw new UsageError(`No login matches --use ${spec}.`, all.length ? `pick one of: ${[...new Set(all)].join(', ')}` : 'name a login by its email');
+        }
+        for (const provider of new Set([...mineHere, ...inHub].map((l) => l.provider))) {
+            const here = mineHere.filter((l) => l.provider === provider), there = inHub.filter((l) => l.provider === provider);
+            const ids = new Set(here.map((l) => l.identity));
+            if (ids.size > 1 || (!here.length && there.length > 1)) {
+                throw new UsageError(`--use ${spec} matches more than one ${provider} login (${[...here, ...there].map((l) => l.file).join(', ')}).`, 'name one by its file name: --use <file>');
+            }
+            const choice = here[0] ? { local: here[0].file, identity: here[0].identity } : { hub: there[0].file };
+            const earlier = by.get(provider);
+            if (earlier !== undefined && earlier !== spec)
+                throw new UsageError(`--use ${earlier} and --use ${spec} both name a ${provider} login; one login per provider is active.`, 'keep one --use per provider');
+            by.set(provider, spec);
+            out.set(provider, choice);
+        }
+    }
+    return out;
+}
+/** When a local login was added: its birth time where the file system keeps one, else its last change. */
+function addedAt(path) {
+    try {
+        const st = statSync(path);
+        return st.birthtimeMs > 0 ? st.birthtimeMs : st.mtimeMs;
+    }
+    catch {
+        return Number.MAX_SAFE_INTEGER;
+    }
+}
+const useSpecs = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []).filter((x) => x.trim() !== '');
 /**
  * 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.
+ *
+ * One login per provider serves requests. `--use <email|file>` (repeatable, one per provider) picks it; otherwise a
+ * provider the hub already serves keeps its active login, and a provider new to the hub starts with this computer's
+ * oldest login of it. Every other login is uploaded with `"disabled": true` and kept in the hub.
  */
 export async function importCliProxy(ctx, opts = {}) {
     if (cliProxyTools.inVm()) {
@@ -676,6 +754,8 @@ export async function importCliProxy(ctx, opts = {}) {
     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);
+    // Which login of each provider is active: checked against this computer's and the hub's before anything is stopped.
+    const use = resolveUse(useSpecs(values.use), local, ensured.logins);
     // 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;
@@ -689,7 +769,8 @@ export async function importCliProxy(ctx, opts = {}) {
     const uploaded = [], kept = [];
     const added = [], already = [];
     let movedAside = [];
-    if (local?.logins.length) {
+    let hubLogins = ensured.logins;
+    if (local?.logins.length || use.size) {
         const opened = await hub.open(false);
         if (!opened)
             throw new HubError('The hub was deleted during the import.', `run: ${AGAIN}`);
@@ -697,34 +778,13 @@ export async function importCliProxy(ctx, opts = {}) {
         // 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);
-            }
+            hubLogins = await uploadLogins(opened.ws, local, use, { uploaded, kept, added, already });
         });
         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?.logins.length)
+            movedAside = moveAuthFilesAside(local.authDirs);
     }
     if (local) {
         new AgentStateStore(ctx.store.dir).update((doc) => {
@@ -757,12 +817,89 @@ export async function importCliProxy(ctx, opts = {}) {
             machine = { error: err instanceof Error ? err.message : String(err) };
         }
     }
-    const accounts = await hubAccounts(ensured.info).catch(() => null);
+    const activeFiles = new Set(hubLogins.filter((l) => l.active).map((l) => l.file));
+    const accounts = await hubAccounts(ensured.info).then((a) => markActive(a, activeFiles), () => 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,
+        logins: { uploaded, kept, added, already, moved_aside: movedAside.map((m) => m.to), active: refs(hubLogins, true), disabled: refs(hubLogins, false) },
+        config: ensured.config ? 'from_this_computer' : 'kept', local: stop.result, port: local?.port ?? CLI_PROXY_PORT, forwarder: { launchd }, machine, dropped: ensured.config?.dropped ?? [], accounts,
     };
 }
+/**
+ * Under the hub's logins lock: uploads this computer's logins the hub lacks (a login that is not its provider's active
+ * one arrives with `"disabled": true`), then keeps one login per provider enabled. Returns the hub's logins after.
+ */
+async function uploadLogins(ws, local, use, out) {
+    const inHub = new Map();
+    const providersInHub = new Set();
+    const present = await ws.authFiles();
+    for (const rel of present) {
+        const text = await ws.read(`${HUB_AUTH_DIR}/${rel}`);
+        const id = text === null ? `file:${rel}` : loginIdentity(text, rel);
+        if (!inHub.has(id))
+            inHub.set(id, rel);
+        const type = (() => { try {
+            const t = JSON.parse(text ?? '').type;
+            return typeof t === 'string' && t.trim() ? t.trim().toLowerCase() : null;
+        }
+        catch {
+            return null;
+        } })();
+        if (type && !/^sfa-[^/]+\.json$/.test(rel))
+            providersInHub.add(type);
+    }
+    const names = new Set(present);
+    const logins = (local?.logins ?? []).map((login) => {
+        const path = join(local.authDir, login.file);
+        const text = readFileSync(path, 'utf8');
+        let disabled = false;
+        try {
+            disabled = JSON.parse(text).disabled === true;
+        }
+        catch { /* not JSON */ }
+        return { ...login, text, identity: loginIdentity(text, login.file), at: addedAt(path), disabled };
+    });
+    // The identity each provider's active login has after this import: --use, else (a provider new to the hub) this
+    // computer's oldest enabled login of it, else its oldest. A provider the hub serves keeps its active login.
+    const target = new Map();
+    for (const [provider, choice] of use)
+        if ('local' in choice)
+            target.set(provider, choice.identity);
+    for (const l of [...logins].sort((a, b) => Number(a.disabled) - Number(b.disabled) || a.at - b.at || (a.file < b.file ? -1 : 1))) {
+        const p = l.provider?.toLowerCase();
+        if (p && !use.has(p) && !providersInHub.has(p) && !target.has(p))
+            target.set(p, l.identity);
+    }
+    for (const login of logins) {
+        const p = login.provider?.toLowerCase() ?? null;
+        // Only a provider new to the hub gets its chosen login enabled on upload. Next to a login the hub already serves,
+        // every upload arrives disabled (two enabled logins would fail over between each other); enforceActiveLogins below
+        // then disables the old one before it enables the chosen one.
+        const content = p === null || (target.get(p) === login.identity && !providersInHub.has(p)) ? login.text : (withDisabled(login.text, true) ?? login.text);
+        const r = inHub.has(login.identity) || names.has(login.file) ? null : await ws.sh(ADD_AUTH_SCRIPT, [login.file], { stdin: content });
+        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') {
+            out.kept.push(login.file);
+            out.already.push({ provider: login.provider, email: login.email });
+            continue;
+        }
+        out.uploaded.push(login.file);
+        out.added.push({ provider: login.provider, email: login.email });
+        inHub.set(login.identity, login.file);
+        names.add(login.file);
+    }
+    const prefer = {};
+    for (const [provider, choice] of use) {
+        const file = 'hub' in choice ? choice.hub : inHub.get(choice.identity);
+        if (file !== undefined)
+            prefer[provider] = file;
+    }
+    for (const [provider, identity] of target)
+        if (prefer[provider] === undefined && inHub.has(identity))
+            prefer[provider] = inHub.get(identity);
+    return enforceActiveLogins(ws, prefer);
+}
 /**
  * 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
@@ -840,6 +977,73 @@ async function exportHandler(ctx, values) {
     ].join('\n') + '\n');
     return 0;
 }
+/**
+ * `shard cli-proxy use <email|file>`: makes that login its provider's active one in the hub (an email with a Claude
+ * and a Codex login sets both); the provider's other logins stay in the hub, disabled. Under the hub's logins lock.
+ */
+export async function useCliProxyLogin(ctx, spec, opts = {}) {
+    if (cliProxyTools.inVm())
+        throw new UsageError('shard cli-proxy use runs on a computer connected to your hosted CLIProxyAPI; this is a Shardflux VM.', 'run it on that computer: shard cli-proxy use <email>');
+    if (!spec.trim())
+        throw new UsageError('Name the login to make active.', 'run: shard cli-proxy use <email>');
+    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 UsageError('This account has no hosted CLIProxyAPI yet.', `move yours: ${AGAIN}`);
+    return opened.ws.withLock('logins', async () => {
+        const before = await listHubLogins(opened.ws);
+        const matches = matchLogins(spec, before);
+        if (!matches.length) {
+            const all = before.filter((l) => l.provider).map((l) => `${l.provider} ${loginName(l)}`);
+            throw new UsageError(`No login in your hosted CLIProxyAPI matches ${spec}.`, all.length ? `pick one of: ${all.join(', ')}` : `add yours: ${AGAIN}`);
+        }
+        const prefer = {};
+        for (const provider of new Set(matches.map((l) => l.provider))) {
+            const mine = matches.filter((l) => l.provider === provider);
+            if (mine.length > 1)
+                throw new UsageError(`${spec} matches more than one ${provider} login (${mine.map((l) => l.file).join(', ')}).`, 'name one by its file name: shard cli-proxy use <file>');
+            prefer[provider] = mine[0].file;
+        }
+        const after = await enforceActiveLogins(opened.ws, prefer);
+        const ref = (l) => ({ provider: l.provider, email: l.email, file: l.file });
+        const switched = Object.entries(prefer).map(([provider, file]) => {
+            const was = before.find((l) => l.provider === provider && l.active);
+            return { provider, from: was ? ref(was) : null, to: ref(after.find((l) => l.file === file)) };
+        });
+        return { switched, active: refs(after, true), disabled: refs(after, false) };
+    });
+}
+async function useHandler(ctx, values, positionals) {
+    const spec = positionals[0] ?? (typeof values.login === 'string' ? values.login : '');
+    const r = await useCliProxyLogin(ctx, spec);
+    if (ctx.json) {
+        ctx.io.stdout.write(json(r));
+        return 0;
+    }
+    const lines = r.switched.map((s) => (s.from?.file === s.to.file
+        ? `${loginName(s.to)} is already your active ${s.provider} login.`
+        : `Active ${s.provider} login: ${loginName(s.to)}. Claude Code, Codex and T3 Code use it from their next request.`));
+    for (const provider of new Set(r.switched.map((s) => s.provider))) {
+        const others = r.disabled.filter((l) => l.provider === provider);
+        if (others.length)
+            lines.push(`Kept in the hub, disabled: ${others.map(loginName).join(', ')}.`);
+    }
+    ctx.io.stdout.write(`${lines.join('\n')}\n`);
+    return 0;
+}
+/** The hub's active.json as a set of files (null when it cannot be read: status then marks a provider's only enabled login). */
+async function activeFilesOf(hub) {
+    try {
+        const opened = await hub.open(false);
+        if (!opened)
+            return null;
+        const text = await opened.ws.read(HUB_ACTIVE_FILE);
+        return text === null ? null : new Set(Object.values(parseActive(text)));
+    }
+    catch {
+        return null;
+    }
+}
 // ---- 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;
@@ -921,6 +1125,8 @@ async function status(ctx, values) {
         }
         if (health.ok)
             accounts = await hubAccounts(info).catch(() => null);
+        if (accounts)
+            accounts = markActive(accounts, await activeFilesOf(hub));
     }
     const identity = await cliProxyTools.identity();
     const launchd = existsSync(forwarderPlistPath(ctx.io.env.HOME || homedir()));
@@ -948,6 +1154,8 @@ async function importHandler(ctx, values) {
         ...(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.logins.active.length ? [`Active logins: ${r.logins.active.map((l) => `${l.provider} ${loginName(l)}`).join(', ')}.`] : []),
+        ...(r.logins.disabled.length ? [`Kept in the hub, disabled: ${r.logins.disabled.map((l) => `${l.provider} ${loginName(l)}`).join(', ')}. Switch any time: shard cli-proxy use <email>`] : []),
         ...(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}).` : '',
@@ -961,9 +1169,12 @@ async function importHandler(ctx, values) {
 async function forwardHandler(ctx) {
     const source = hubInfoSource(ctx.store.dir);
     const log = (line) => void ctx.io.stderr.write(`${new Date().toISOString()} ${line}\n`);
+    let checks = null;
     const forwarder = new CliProxyForwarder({
         hub: source,
         log,
+        // The first request after the hub slept: check its logins as it wakes.
+        onRequest: () => checks?.nudge(),
         repair: async () => {
             const info = source();
             if (!info || info.api_url !== ctx.apiUrl)
@@ -981,14 +1192,68 @@ async function forwardHandler(ctx) {
     if (!source())
         log('not connected to a hosted CLIProxyAPI yet; answering 503 until shard cli-proxy import connects this computer');
     await forwarder.listen();
+    checks = hubLoginChecks(ctx, source, log);
     await new Promise((resolve) => {
         if (ctx.signal.aborted)
             return resolve();
         ctx.signal.addEventListener('abort', () => resolve(), { once: true });
     });
+    checks.stop();
     await forwarder.close();
     return 0;
 }
+/** How often the forwarder checks that the hub serves one login per provider while it runs. */
+export const HUB_LOGIN_CHECK_MS = 15 * 60_000;
+/** How soon it looks again when the hub was asleep (a VM's request may wake it any moment; looking never wakes it). */
+export const HUB_LOGIN_ASLEEP_MS = 60_000;
+/** The least time between two checks a request asks for (requests come in bursts). */
+export const HUB_LOGIN_NUDGE_MS = 10_000;
+/**
+ * The forwarder's check that the hub serves one login per provider (enforceHubLoginsIfRunning), never waking the hub:
+ * at start; then every HUB_LOGIN_CHECK_MS while it runs and every HUB_LOGIN_ASLEEP_MS while it sleeps; and at the first
+ * request after it slept (nudge), so a hub set up before one login per provider cannot fail over between logins for
+ * long after it wakes. One check at a time.
+ */
+export function hubLoginChecks(ctx, source, log, opts = {}) {
+    const everyMs = opts.everyMs ?? HUB_LOGIN_CHECK_MS, asleepMs = opts.asleepMs ?? HUB_LOGIN_ASLEEP_MS, nudgeMs = opts.nudgeMs ?? HUB_LOGIN_NUDGE_MS;
+    let running = false, stopped = false, last = null, lastAt = 0;
+    let timer;
+    const schedule = (ms) => { clearTimeout(timer); if (!stopped) {
+        timer = setTimeout(() => void check(), ms);
+        timer.unref?.();
+    } };
+    const check = async () => {
+        const info = source();
+        if (running || stopped)
+            return;
+        if (!info || info.api_url !== ctx.apiUrl) {
+            schedule(everyMs);
+            return;
+        }
+        running = true;
+        try {
+            const hub = opts.hub ?? sdkHubCloud(ctx.cloud(), { signal: ctx.signal, wakeTimeoutMs: ctx.wakeTimeoutMs, agentLabel: ctx.agentLabel });
+            last = await enforceHubLoginsIfRunning(hub, info.workspace_id);
+            if (last === 'enforced')
+                log('the hub serves one login per provider');
+        }
+        catch (err) {
+            last = 'failed';
+            log(`could not check the hub's logins (${describeError(err).message}); checking again soon`);
+        }
+        finally {
+            running = false;
+            lastAt = Date.now();
+            schedule(last === 'enforced' || last === 'missing' ? everyMs : asleepMs);
+        }
+    };
+    void check();
+    return {
+        nudge() { if (!running && !stopped && (last !== 'enforced' || Date.now() - lastAt >= everyMs) && Date.now() - lastAt >= nudgeMs)
+            void check(); },
+        stop() { stopped = true; clearTimeout(timer); },
+    };
+}
 /**
  * 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.
@@ -1012,5 +1277,6 @@ export const CLI_PROXY_HANDLERS = {
     'cli-proxy': status,
     'cli-proxy import': importHandler,
     'cli-proxy export': exportHandler,
+    'cli-proxy use': useHandler,
     'cli-proxy forward': forwardHandler,
 };

package/dist/client-settings.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `shard settings` (0.20.1+): this computer's settings for its cloud conversations, kept in agents.json next to
+ * open_in and terminal_app. It sets the title marker (title_prefix), and shows where conversations open and the
+ * terminal app (set with `shard agents targets --open-in/--terminal`). The menu bar and the Linux app read and write
+ * the marker through it.
+ *
+ * The marker is what a conversation's Claude session title starts with in claude.ai and the Claude app
+ * ("☁ Fix login bug · todo-app"). Stored: absent for the platform's default, "" for none, else the text; the guest
+ * adds the space after it. New conversations send it as `title_prefix`, legacy agent launches as SF_TITLE_PREFIX.
+ */
+import type { Handler } from './commands.js';
+import type { OpenIn } from './t3-mode.js';
+/** The platform's marker (the guest's "☁ " without its space). */
+export declare const DEFAULT_TITLE_PREFIX = "\u2601";
+/** At most this many characters on one line, as the API takes it (POST /v1/conversations title_prefix). */
+export declare const TITLE_PREFIX_MAX = 16;
+/** `--title-prefix <text|none|default>`: null for the default (the stored choice is removed), "" for none. */
+export declare function parseTitlePrefix(spec: string): string | null;
+/** The marker this computer chose: undefined for the default (nothing is sent), "" for none. An unreadable or invalid
+ * stored value counts as the default, so it never blocks a start. */
+export declare function storedTitlePrefix(dir: string): string | undefined;
+export declare function saveTitlePrefix(dir: string, choice: string | null): void;
+/** `shard settings --json`. title_prefix: null is the default, "" none. open_in and terminal_app are the saved
+ * choices (null: automatic). */
+export declare function clientSettings(dir: string): {
+    title_prefix: string | null;
+    title_prefix_default: string;
+    open_in: {
+        claude: OpenIn | null;
+        codex: OpenIn | null;
+    };
+    terminal_app: {
+        name: string;
+        id: import("./terminal-apps.js").TerminalId;
+        mode: import("./terminal-apps.js").TerminalMode;
+    } | null;
+};
+export declare function settingsText(s: ReturnType<typeof clientSettings>): string;
+export declare const SETTINGS_HANDLERS: Record<string, Handler>;

package/dist/client-settings.js

@@ -0,0 +1,91 @@
+import { out } from "./commands.js";
+import { AgentStateStore } from "./agent-state.js";
+import { UsageError } from "./errors.js";
+import { objectValue } from "./acp-rpc.js";
+import { openInTargets } from "./t3-mode.js";
+import { storedTerminal, terminalName } from "./terminal-apps.js";
+/** The platform's marker (the guest's "☁ " without its space). */
+export const DEFAULT_TITLE_PREFIX = '☁';
+/** At most this many characters on one line, as the API takes it (POST /v1/conversations title_prefix). */
+export const TITLE_PREFIX_MAX = 16;
+const SAMPLE = 'Fix login bug · todo-app';
+// The API's pattern: no C0 control characters and no DEL.
+const control = (value) => [...value].some(c => { const n = c.codePointAt(0); return n < 0x20 || n === 0x7f; });
+const validPrefix = (value) => !control(value) && [...value].length <= TITLE_PREFIX_MAX;
+/** `--title-prefix <text|none|default>`: null for the default (the stored choice is removed), "" for none. */
+export function parseTitlePrefix(spec) {
+    const text = spec.trim();
+    if (text === 'default')
+        return null;
+    if (text === 'none' || text === '')
+        return '';
+    if (control(text))
+        throw new UsageError('--title-prefix is one line of text: no tabs, line breaks or control characters.');
+    if ([...text].length > TITLE_PREFIX_MAX)
+        throw new UsageError(`--title-prefix is at most ${TITLE_PREFIX_MAX} characters (none for no marker, default for ${DEFAULT_TITLE_PREFIX}).`);
+    return text;
+}
+/** The marker this computer chose: undefined for the default (nothing is sent), "" for none. An unreadable or invalid
+ * stored value counts as the default, so it never blocks a start. */
+export function storedTitlePrefix(dir) {
+    try {
+        const value = new AgentStateStore(dir).read().title_prefix;
+        return typeof value === 'string' && validPrefix(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveTitlePrefix(dir, choice) {
+    new AgentStateStore(dir).update(doc => { if (choice === null)
+        delete doc.title_prefix;
+    else
+        doc.title_prefix = choice; });
+}
+/** `shard settings --json`. title_prefix: null is the default, "" none. open_in and terminal_app are the saved
+ * choices (null: automatic). */
+export function clientSettings(dir) {
+    const doc = new AgentStateStore(dir).read();
+    const saved = objectValue(doc.open_in);
+    const openIn = (app) => {
+        const value = saved[app];
+        return typeof value === 'string' && openInTargets(app).includes(value) ? value : null;
+    };
+    const terminal = storedTerminal(dir);
+    const prefix = typeof doc.title_prefix === 'string' && validPrefix(doc.title_prefix) ? doc.title_prefix : null;
+    return {
+        title_prefix: prefix,
+        title_prefix_default: DEFAULT_TITLE_PREFIX,
+        open_in: { claude: openIn('claude'), codex: openIn('codex') },
+        terminal_app: terminal ? { ...terminal, name: terminalName(terminal.id) } : null,
+    };
+}
+const sampleTitle = (prefix) => `${prefix === null ? DEFAULT_TITLE_PREFIX + ' ' : prefix ? prefix + ' ' : ''}${SAMPLE}`;
+const markerLine = (prefix) => prefix === null ? `${DEFAULT_TITLE_PREFIX} (default)` : prefix === '' ? 'none' : prefix;
+export function settingsText(s) {
+    const target = (t) => t ?? 'automatic';
+    return [
+        `Title marker   ${markerLine(s.title_prefix)}   "${sampleTitle(s.title_prefix)}"`,
+        `Open in        Claude: ${target(s.open_in.claude)} · Codex: ${target(s.open_in.codex)}`,
+        `Terminal app   ${s.terminal_app ? `${s.terminal_app.name}, ${s.terminal_app.mode === 'tab' ? 'new tab' : 'new window'}` : 'automatic'}`,
+        '',
+        'Change the marker with shard settings --title-prefix <text|none|default>; where conversations open with shard agents targets --open-in and --terminal.',
+    ].join('\n') + '\n';
+}
+function settings(ctx, values) {
+    const spec = values['title-prefix'];
+    if (spec !== undefined && typeof spec !== 'string')
+        throw new UsageError('--title-prefix takes text, none or default.');
+    if (typeof spec === 'string') {
+        const choice = parseTitlePrefix(spec);
+        saveTitlePrefix(ctx.store.dir, choice);
+        const s = clientSettings(ctx.store.dir);
+        out(ctx, `${s.title_prefix === '' ? 'New conversations have no title marker' : `New conversations’ titles start with ${markerLine(s.title_prefix)}`}: "${sampleTitle(s.title_prefix)}".\n`, s);
+        return 0;
+    }
+    const s = clientSettings(ctx.store.dir);
+    out(ctx, settingsText(s), s);
+    return 0;
+}
+// A refused --title-prefix rejects the command's promise (a usage error, exit 2) rather than throwing.
+export const SETTINGS_HANDLERS = { settings: (ctx, values) => Promise.resolve().then(() => settings(ctx, values)) };

package/dist/codex-cloud.d.ts

@@ -3,6 +3,7 @@ import type { Ctx, Handler } from './commands.js';
 import type { Values } from './args.js';
 import type { ModelChoice } from './agent-models.js';
 import type { Conversation } from './conversations.js';
+import type { LocalConversation } from './conversations.js';
 import type { InitialImage } from './initial-prompt.js';
 /** Only provider-returned task ids enter the registered Codex deep-link route. */
 export declare function openCodexThread(task: CodexCloudTask, env: Ctx['io']['env']): Promise<void>;
@@ -48,5 +49,9 @@ export declare function ensureCodexCloud(ctx: Ctx): Promise<{
     last_seen_at: string | null;
 }>;
 export declare function launchCodexCloud(ctx: Ctx, values: Values, path: string, images?: readonly InitialImage[]): Promise<number>;
+/** A start whose carrying process said so in the last 45 s. */
+export declare const startCarried: (start: NonNullable<LocalConversation["cloud_start"]>) => boolean;
 export declare function openCodexConversation(ctx: Ctx, c: Conversation): Promise<number>;
+/** Continues the same accepted identity, never creates a replacement VM/chat. */
+export declare function resumeCloudStartup(ctx: Ctx, c: Conversation): Promise<CodexCloudTask>;
 export declare const CODEX_CLOUD_HANDLERS: Record<string, Handler>;