@shardflux/cli 0.20.0 → 0.23.0

package/dist/cli-proxy.js

@@ -1,11 +1,14 @@
 /**
- * `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)`.
+ *
+ * The hub is the user's own CLIProxyAPI: it routes requests across their logins as their config says, and each login
+ * stays enabled or disabled as they left it. `shard cli-proxy use` is their switch: one login for a provider, or all.
  */
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
@@ -18,7 +21,7 @@ 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_AUTH_DIR, HUB_KEY, HubError, SET_ASIDE_SCRIPT, STOP_SCRIPT, ensureCliProxyHub, hubCallback, listHubLogins, readHubInfo, sdkHubCloud, useHubLogins, vmHubInfoText, writeHubInfo } from "./cli-proxy-hub.js";
 import { CLI_VERSION } from "./args.js";
 import { UsageError } from "./errors.js";
 import { json } from "./format.js";
@@ -625,6 +628,12 @@ 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;
+}
 /** 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 +649,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: f.disabled !== true,
     }));
 }
 /** Whether the hub answers /healthz through its callback URL, and the edge's reason when it does not. */
@@ -654,11 +665,61 @@ export async function hubHealth(info, timeoutMs = 45_000) {
     }
 }
 const accountLine = (a) => `  ${a.provider.padEnd(8)} ${a.email ?? '(no email)'}${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 the one login that serves its 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; --use names one login per provider.`, 'keep one --use per provider');
+            by.set(provider, spec);
+            out.set(provider, choice);
+        }
+    }
+    return out;
+}
+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.
+ *
+ * Each login arrives as it is on this computer (enabled or disabled), and the hub routes across the enabled ones as
+ * the user's config says. `--use <email|file>` (repeatable, one per provider) makes that login the only one serving
+ * its provider (the provider's others are kept in the hub, disabled), as `shard cli-proxy use` does.
  */
 export async function importCliProxy(ctx, opts = {}) {
     if (cliProxyTools.inVm()) {
@@ -676,6 +737,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 +752,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 +761,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) => {
@@ -760,9 +803,50 @@ export async function importCliProxy(ctx, opts = {}) {
     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,
+        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, each as it is (enabled or disabled), then
+ * applies --use. Returns the hub's logins after.
+ */
+async function uploadLogins(ws, local, use, out) {
+    const inHub = new Map();
+    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 names = new Set(present);
+    for (const login of local?.logins ?? []) {
+        const text = readFileSync(join(local.authDir, login.file), 'utf8');
+        const identity = loginIdentity(text, login.file);
+        const r = inHub.has(identity) || names.has(login.file) ? null : await 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') {
+            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(identity, login.file);
+        names.add(login.file);
+    }
+    if (!use.size)
+        return listHubLogins(ws);
+    const only = {};
+    for (const [provider, choice] of use) {
+        const file = 'hub' in choice ? choice.hub : inHub.get(choice.identity);
+        if (file !== undefined)
+            only[provider] = file;
+    }
+    return useHubLogins(ws, { only });
+}
 /**
  * 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 +924,69 @@ async function exportHandler(ctx, values) {
     ].join('\n') + '\n');
     return 0;
 }
+/**
+ * `shard cli-proxy use <email|file>`: that login alone serves its provider (an email with a Claude and a Codex login
+ * sets both); the provider's other logins stay in the hub, disabled. `--all`: every login serves again, and the hub
+ * routes across them as its config says. 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 (!opts.all && !spec.trim())
+        throw new UsageError('Name the login to use, or --all for every login.', 'run: shard cli-proxy use <email>');
+    if (opts.all && spec.trim())
+        throw new UsageError('Name a login or use --all, not both.', 'run: shard cli-proxy use --all');
+    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);
+        if (opts.all) {
+            const after = await useHubLogins(opened.ws, { all: true });
+            return { switched: [], active: refs(after, true), disabled: refs(after, false) };
+        }
+        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 only = {};
+        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>');
+            only[provider] = mine[0].file;
+        }
+        const after = await useHubLogins(opened.ws, { only });
+        const ref = (l) => ({ provider: l.provider, email: l.email, file: l.file });
+        const switched = Object.entries(only).map(([provider, file]) => {
+            const was = before.filter((l) => l.provider === provider && l.active);
+            return { provider, from: was.length === 1 ? ref(was[0]) : 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, { all: values.all === true });
+    if (ctx.json) {
+        ctx.io.stdout.write(json(r));
+        return 0;
+    }
+    const lines = values.all === true
+        ? [`Every login serves requests, routed as your CLIProxyAPI config says: ${r.active.map((l) => `${l.provider} ${loginName(l)}`).join(', ') || 'none yet'}.`]
+        : r.switched.map((s) => (s.from?.file === s.to.file
+            ? `${loginName(s.to)} already serves your ${s.provider} requests.`
+            : `${loginName(s.to)} serves your ${s.provider} requests now. 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(', ')}. Use them all again: shard cli-proxy use --all`);
+    }
+    ctx.io.stdout.write(`${lines.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;
@@ -948,6 +1095,7 @@ 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.disabled.length ? [`Kept in the hub, disabled: ${r.logins.disabled.map((l) => `${l.provider} ${loginName(l)}`).join(', ')}. Use them too: shard cli-proxy use --all`] : []),
         ...(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}).` : '',
@@ -1012,5 +1160,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,12 +3,18 @@ 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>;
+/** Cloud threads open in the browser, preserving the durable provider destination on every OS. */
+export declare function openCodexThread(task: CodexCloudTask, env: Ctx['io']['env'], platform?: NodeJS.Platform): Promise<void>;
 export declare function submitCloudInitialPrompt(ctx: Ctx, c: Conversation, prompt: string, workspaceKey: string): Promise<void>;
-/** Prints the Cloud thread (and its link) and opens it in the Codex app; --json prints it instead. */
+/** Prints the Cloud thread (and its link) and opens it in your browser; --json prints it instead. */
 export declare function printCloudThread(ctx: Ctx, c: Conversation, task: CodexCloudTask, submitted?: boolean, choice?: ModelChoice): Promise<void>;
+/**
+ * A Cloud conversation where the Codex app cannot show it (0.23.0+): where its chat lives, whether it waits for an
+ * answer, and how to answer and follow it from here. Never a new start: the conversation exists.
+ */
+export declare function cloudChatElsewhere(c: Pick<Conversation, 'id' | 'key' | 'state'>, url: string): string;
 /** How long the account's Codex remote device may take to come up before it counts as stuck. */
 export declare const CODEX_STARTING_LIMIT_MS: number;
 export type CodexConnectorView = {
@@ -48,5 +54,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>;
-export declare function openCodexConversation(ctx: Ctx, c: Conversation): 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, history?: true | string): 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>;