@shardflux/cli 0.14.4 → 0.15.0

package/dist/agent-terminal.js

@@ -1,6 +1,11 @@
 import { StringDecoder } from 'node:string_decoder';
 import { PtyConnection, ShardfluxApiError, ShardfluxProtocolError, exitCodePosix } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
+/** The workspace (or the VM under this terminal) is asleep: the user's next keystroke wakes it. */
+export function sleepingAttach(error) {
+    return error instanceof ShardfluxApiError && error.code === 'workspace_not_running';
+}
+const ASLEEP_NOTICE = '\r\n\x1b[2m· asleep. Type to wake it.\x1b[0m\r\n';
 export function retryableAttach(error) {
     if (error instanceof ShardfluxProtocolError && /invalid|byte gap|omitted/.test(error.message))
         return false;
@@ -50,6 +55,7 @@ export async function attachTerminal(options) {
         const size = dimensions();
         connection?.resize(Math.min(1000, Math.max(1, size.rows)), Math.min(1000, Math.max(1, size.cols)));
     };
+    let typed;
     const send = (bytes) => {
         if (!bytes.length)
             return;
@@ -75,10 +81,21 @@ export async function attachTerminal(options) {
                 inputFailure = new UsageError('terminal input exceeded the reconnect buffer');
                 controller.abort(inputFailure);
             }
-            else
+            else {
                 pending.push(bytes);
+                typed?.();
+            }
         }
     };
+    const untilTyped = () => new Promise((resolve) => {
+        if (pending.length || signal.aborted) {
+            resolve();
+            return;
+        }
+        const done = () => { typed = undefined; signal.removeEventListener('abort', done); resolve(); };
+        typed = done;
+        signal.addEventListener('abort', done, { once: true });
+    });
     const data = (value) => {
         const bytes = typeof value === 'string' ? Buffer.from(value) : value;
         if (promptAnswer) {
@@ -147,13 +164,25 @@ export async function attachTerminal(options) {
         controller.abort();
     } });
     let reconnects = 0;
+    let asleep = false;
     try {
         while (!signal.aborted) {
             try {
-                if (reconnects) {
+                if (asleep) {
+                    // Asleep: an open terminal is not a reason to wake the workspace. The first keystroke is.
+                    asleep = false;
+                    io.stderr.write(ASLEEP_NOTICE);
+                    await untilTyped();
+                    if (signal.aborted)
+                        break;
                     options.invalidate();
                     await options.wake(signal);
                 }
+                else if (reconnects) {
+                    options.invalidate();
+                    if (!options.asleep)
+                        await options.wake(signal);
+                }
                 connection = await options.connect(cursor.offset, signal);
                 acceptingInput = true;
                 resize();
@@ -179,6 +208,10 @@ export async function attachTerminal(options) {
                     break;
                 if (!retryableAttach(error))
                     throw error;
+                if (options.asleep && (sleepingAttach(error) || await options.asleep(signal).catch(() => false))) {
+                    asleep = true;
+                    continue;
+                }
             }
             finally {
                 const previous = connection;
@@ -204,6 +237,51 @@ export async function attachTerminal(options) {
         stdin.pause?.();
     }
 }
-export function cellConnector(cell, sessionId) {
-    return (offset, signal) => PtyConnection.attach(cell, sessionId, offset, signal);
+/** Reads the workspace without waking it: suspended, or on its way there. */
+export async function workspaceAsleep(ws) {
+    await ws.refresh();
+    return ws.desiredState === 'suspended' || ws.state === 'suspending' || ws.state === 'suspended';
+}
+/** A host without passive attach refuses it before any output; the terminal then attaches as an ordinary one. */
+export function passiveUnavailable(error) {
+    return error instanceof ShardfluxApiError && error.reason === 'host_feature_unavailable' && error.details?.feature === 'passive_pty';
+}
+/**
+ * Attaches a PTY. `passive` (the agent terminal, 0.14.4+) holds the workspace only while bytes move through it, so a
+ * waiting agent's workspace parks and suspends under an open terminal, and input still wakes it; on a host without
+ * passive attach the next attach is an ordinary one. An ordinary attach wakes a parked workspace and holds it.
+ */
+export function cellConnector(cell, sessionId, opts = {}) {
+    let passive = opts.passive === true;
+    const fallback = (error) => {
+        if (!passive || !passiveUnavailable(error))
+            return error;
+        passive = false;
+        return new ShardfluxProtocolError('agent terminal host has no passive attach', 0, 'cell');
+    };
+    return async (offset, signal) => {
+        const { url, token } = await cell.pty.attachUrl(sessionId, offset);
+        const target = new URL(url);
+        if (passive)
+            target.searchParams.set('passive', 'true');
+        const connection = new PtyConnection(target.toString(), token, signal);
+        try {
+            await connection.ready;
+        }
+        catch (error) {
+            await connection.close();
+            throw fallback(error);
+        }
+        return {
+            input: (bytes) => connection.input(bytes), resize: (rows, cols) => connection.resize(rows, cols), close: () => connection.close(),
+            async *messages() {
+                try {
+                    yield* connection.messages();
+                }
+                catch (error) {
+                    throw fallback(error);
+                }
+            },
+        };
+    };
 }

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.14.4";
+export declare const CLI_VERSION = "0.15.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;
@@ -6,6 +6,8 @@ export interface OptionSpec {
     /** Placeholder shown in help, e.g. `<slug>`. */
     value?: string;
     description: string;
+    /** Accept the option for compatibility but omit it from help. */
+    hidden?: boolean;
 }
 export interface PositionalSpec {
     name: string;

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.14.4';
+export const CLI_VERSION = '0.15.0';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -268,7 +268,7 @@ const KEY_COMMANDS = [
             'delete-after-idle': { type: 'string', value: '<days>d', description: 'Delete this persistent workspace after 1..3650 idle days (e.g. 14d).' },
             like: { type: 'string', value: '<id|key>', description: 'Open a fresh workspace with the source’s template and configuration.' },
             volume: { type: 'string', multiple: true, value: '<name:/path[:ro]>', description: 'Replace the named volume mounts; repeat for each mount.' },
-            reachable: { type: 'string', value: '<duration>', description: 'Keep waiting agents reachable (default 30m; 0 off; maximum 24h).' },
+            reachable: { type: 'string', value: '<duration>', hidden: true, description: 'Deprecated; ignored. Claude conversations stay reachable without a time limit.' },
             'agent-idle-grace-seconds': { type: 'string', value: '<0-3600>', description: 'Grace after a coding agent waits or exits (default 300 seconds).' },
             'idle-policy': { type: 'string', value: '<policy>', description: 'adaptive, never or fixed:<seconds>.' },
             secret: {
@@ -876,9 +876,10 @@ const KEY_COMMANDS = [
     { path: ['credentials', 'list'], summary: 'Show pending login requests', positionals: [], options: {} },
     { path: ['credentials', 'enable'], summary: 'Enable credential fill in a workspace', positionals: [REF], options: {} },
     { path: ['credentials', 'deny'], summary: 'Deny a login request', positionals: [{ name: 'request-id', required: true }], options: {} },
-    { path: ['credentials', 'forget'], summary: 'Remove a remembered site credential', positionals: [REF, { name: 'site', required: true }], options: {} },
+    { path: ['credentials', 'forget'], summary: 'Remove a remembered site credential', positionals: [REF, { name: 'site', required: true }], options: { scope: { type: 'string', value: '<conversation|project|machine>', description: 'Remembered sign-in scope (default project).' } } },
     { path: ['credentials', 'approve'], summary: 'Approve a login directly from your vault', positionals: [{ name: 'request-id', required: true }], options: {
             from: { type: 'string', description: 'hsec, 1password, bitwarden or keychain.' }, item: { type: 'string', description: 'Vault login item name.' },
+            scope: { type: 'string', value: '<ask|project|machine>', description: 'Future-request scope; unattended sign-in uses the same scope.' },
             always: { type: 'boolean', description: 'Always allow these fields for this project on this laptop.' }, remember: { type: 'boolean', description: 'Remember for unattended use, encrypted with AWS KMS.' },
         } },
     {
@@ -1166,8 +1167,12 @@ const AGENT_CREDENTIAL_COMMANDS = [
     ...['sync', 'status', 'forget'].map((action) => ({ path: ['agents', 'credentials', action], summary: `${action} Codex copies and the account's cloud Claude login (contents never printed)`, positionals: [], options: {} })),
     { path: ['agents', 'credentials', 'login'], summary: 'Sign in once to cloud Claude for this account', positionals: [{ name: 'app', required: true }], options: { workspace: { type: 'string', value: '<id|key>', description: 'Use this workspace for the cloud sign-in.' } } },
 ];
+const COMPUTER_OPTION = { type: 'boolean', description: 'Give the new conversation a desktop with a browser its agent drives (computer use).' };
 const AGENT_OPTIONS = {
-    reachable: { type: 'string', value: '<duration>', description: 'Keep waiting agents reachable (default 30m; 0 off; maximum 24h).' },
+    prompt: { type: 'string', value: '<text>', description: 'First user message for a new conversation.' },
+    'prompt-file': { type: 'string', value: '<file|->', description: 'Read the first user message from a UTF-8 file or stdin (-), up to 256 KiB.' },
+    image: { type: 'string', multiple: true, value: '<file|->', description: 'Attach a PNG, JPEG, GIF or WebP image to the first message (repeatable, up to 5 of 10 MiB each; - reads PNG images back to back from stdin) (0.15.0+).' },
+    reachable: { type: 'string', value: '<duration>', hidden: true, description: 'Deprecated; ignored. Claude conversations stay reachable without a time limit.' },
     approvals: { type: 'boolean', description: 'Keep the agent’s permission prompts.' },
 };
 export const PROJECT_COMMAND = {
@@ -1175,6 +1180,7 @@ export const PROJECT_COMMAND = {
     description: 'Opens Claude Code or Codex directly. --resume continues a project conversation. With --json it starts detached and prints the session. Detach with Ctrl-] then d.',
     positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: {
         ...AGENT_OPTIONS,
+        computer: COMPUTER_OPTION,
         new: { type: 'boolean', description: 'Start a new conversation.' },
         resume: { type: 'boolean', description: 'Continue a conversation from this project.' },
         claude: { type: 'boolean', description: 'Same as the claude argument (0.14.4+).' },
@@ -1200,9 +1206,11 @@ const AGENT_COMMANDS = [
             ...(action === 'keep' ? { push: { type: 'boolean', description: 'Push the kept branch to origin and open a PR when gh is installed.' } } : {}),
         },
     })),
-    { path: ['agents', 'open'], summary: 'Attach an agent in the terminal', description: 'Detach with Ctrl-] then d; /exit ends the agent session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|claude-desktop|codex-app|web|t3>', description: 'Where to open the session (default terminal).' } } },
-    { path: ['agents', 'new'], summary: 'Start a session or a named agent', positionals: [{ name: 'agent' }], options: {
+    ...['status', 'enable', 'disable'].map(action => ({ path: ['agents', 'codex', action], summary: `${action} the account's billed Codex Cloud connector`, positionals: [], options: {} })),
+    { path: ['agents', 'open'], summary: 'Open a conversation (Codex Cloud or the native Claude session)', description: 'Codex opens its existing Cloud thread without waking its VM. Claude attaches its native session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|auto|claude-desktop|codex-app|web|t3>', description: 'Where to open a legacy session.' } } },
+    { path: ['agents', 'new'], summary: 'Start a conversation in a fresh VM; Codex opens a genuine Cloud thread', positionals: [{ name: 'agent' }], options: {
             ...AGENT_OPTIONS,
+            computer: COMPUTER_OPTION,
             app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' },
             path: { type: 'string', value: '<path>', description: 'Local project path for first launch.' },
             name: { type: 'string', value: '<name>', description: 'New agent name; copies the project main workspace with --like.' },
@@ -1396,6 +1404,9 @@ function toParseArgsOptions(opts) {
  * returns help text for --help, bare groups and non-TTY bare `shard`.
  */
 export function parseCommandLine(argv, options = {}) {
+    // `acp --login` is the ACP terminal sign-in an editor runs (ACP appends the method's args to `shard acp`).
+    if (argv.length === 2 && argv[0] === 'acp' && argv[1] === '--login')
+        return { kind: 'run', command: { path: ['acp'], summary: '', positionals: [], options: {} }, values: { login: true }, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     if (argv.length === 1 && (argv[0] === 'acp' || argv[0] === 'device-helper'))
         return { kind: 'run', command: { path: [argv[0]], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     const terminator = argv.indexOf('--');
@@ -1559,7 +1570,7 @@ function emailedTokensAsPositionals(rest, command) {
 }
 // ---- help ----------------------------------------------------------------------------------
 function optionLines(opts) {
-    const rows = Object.entries(opts).map(([name, o]) => [`${o.short ? `-${o.short}, ` : '    '}--${name}${o.value ? ` ${o.value}` : ''}`, o.description]);
+    const rows = Object.entries(opts).filter(([, o]) => !o.hidden).map(([name, o]) => [`${o.short ? `-${o.short}, ` : '    '}--${name}${o.value ? ` ${o.value}` : ''}`, o.description]);
     const w = Math.max(0, ...rows.map((r) => r[0].length));
     return rows.map(([l, d]) => `  ${l.padEnd(w)}  ${d}`);
 }
@@ -1574,8 +1585,9 @@ export function commandHelp(c) {
     const lines = [`Usage: ${usageLine(c)}`, '', c.summary + '.'];
     if (c.description)
         lines.push('', c.description);
-    if (Object.keys(c.options).length > 0)
-        lines.push('', 'Options:', ...optionLines(c.options));
+    const options = optionLines(c.options);
+    if (options.length > 0)
+        lines.push('', 'Options:', ...options);
     lines.push('', 'Global options:', ...optionLines(GLOBAL_OPTIONS));
     if (c.examples?.length)
         lines.push('', 'Examples:', ...c.examples.map((e) => `  ${e}`));

package/dist/browser-login.d.ts

@@ -0,0 +1,35 @@
+import type { AccountClientOptions, AuthUser } from '@shardflux/sdk';
+export interface DeviceAuthorization {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+export interface DeviceSession {
+    status: 'authenticated';
+    user: AuthUser;
+    session_token: string;
+    session_expires_at: string;
+}
+export interface DevicePollOptions {
+    signal: AbortSignal;
+    /** Waits `ms` (ends early when the signal aborts). */
+    sleep(ms: number): Promise<void>;
+    now?: () => number;
+    /** A token poll that has not answered after this long is a connection timeout (default 15 s). */
+    requestTimeoutMs?: number;
+}
+/** The default name on the approval page: "shard CLI on <hostname>". */
+export declare function defaultClientName(hostname: string): string;
+/** POST /v1/auth/device. */
+export declare function startDeviceAuthorization(opts: AccountClientOptions, clientName: string, signal: AbortSignal): Promise<DeviceAuthorization>;
+/**
+ * Polls POST /v1/auth/device/token until the session is issued (RFC 8628 §3.4, §3.5): waits `interval` seconds before
+ * each poll; a slow_down adds 5 s (or takes the server's longer interval); a connection failure or timeout doubles the
+ * interval (exponential backoff); 429 waits its Retry-After and 5xx the interval, while the request can still be
+ * approved. Stops on access_denied, expired_token and every other refusal (thrown as the API's error), and when the
+ * request's lifetime has passed.
+ */
+export declare function waitForDeviceSession(opts: AccountClientOptions, d: DeviceAuthorization, poll: DevicePollOptions): Promise<DeviceSession>;

package/dist/browser-login.js

@@ -0,0 +1,145 @@
+/**
+ * `shard auth login --browser` (0.15.0+): sign in by approving this computer in the browser (API contracts §30.5, the
+ * OAuth 2.0 Device Authorization Grant of RFC 8628). POST /v1/auth/device returns a device code (kept in memory only,
+ * never printed) and a user code; the person opens <app>/cli?code=XXXX-XXXX, signs in or signs up there, checks that the
+ * page shows the same code and approves; meanwhile this polls POST /v1/auth/device/token every `interval` seconds
+ * (5 s more after each slow_down) until the API hands over the CLI session, the same kind `shard auth login` saves.
+ *
+ * The Mac app runs it with --json and reads NDJSON on stdout (one object per line):
+ *   {"event":"open","verification_uri_complete":"…","user_code":"ABCD-EFGH","expires_in":600,
+ *    "terms_url":"https://shardflux.dev/terms","privacy_url":"https://shardflux.dev/privacy"}
+ *   {"event":"signed_in","email":"…"}                              (exit 0), or
+ *   {"event":"error","code":"access_denied|expired_token|…","message":"…"}   (exit non-zero)
+ */
+import { ShardfluxApiError, ShardfluxProtocolError } from '@shardflux/sdk';
+const DEVICE_CODE = /^sfd_[A-Za-z0-9_-]{43}$/;
+const USER_CODE = /^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$/;
+const SESSION_TOKEN = /^sfu_[A-Za-z0-9_-]{43}$/;
+/** RFC 8628 §3.5: every slow_down adds at least 5 seconds to the interval (more when the server names a longer one). */
+const SLOW_DOWN_STEP_SECONDS = 5;
+const REQUEST_TIMEOUT_MS = 15_000;
+/** Polls keep going this long past expires_in while the API cannot be reached (it answers expired_token itself). */
+const EXPIRY_GRACE_MS = 30_000;
+/** The default name on the approval page: "shard CLI on <hostname>". */
+export function defaultClientName(hostname) {
+    const host = hostname.trim().replace(/\.local$/i, '');
+    return host ? `shard CLI on ${host}`.slice(0, 100) : 'shard CLI';
+}
+async function call(opts, path, body, signal) {
+    const doFetch = opts.fetch ?? fetch;
+    const headers = { 'content-type': 'application/json', accept: 'application/json' };
+    if (opts.userAgent)
+        headers['user-agent'] = opts.userAgent;
+    const base = (opts.baseUrl ?? 'https://api.shardflux.dev').replace(/\/+$/, '');
+    const res = await doFetch(`${base}${path}`, { method: 'POST', headers, body: JSON.stringify(body), signal });
+    const text = await res.text();
+    let parsed = null;
+    if (text.length > 0) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new ShardfluxProtocolError(`POST ${path} answered ${res.status} without JSON`, res.status, 'api');
+        }
+    }
+    const ra = Number(res.headers.get('retry-after'));
+    return { status: res.status, body: parsed, retryAfter: Number.isFinite(ra) && ra > 0 ? ra : undefined };
+}
+function apiError(status, body, retryAfter, path) {
+    const e = body?.error;
+    if (!e || typeof e.code !== 'string' || typeof e.message !== 'string')
+        return new ShardfluxProtocolError(`POST ${path} answered ${status} without an error body`, status, 'api');
+    return new ShardfluxApiError(status, body, 'api', retryAfter);
+}
+/** An error the CLI raises itself in the API's shape (the request expired while the API could not be reached). */
+function localError(code, message) {
+    return new ShardfluxApiError(400, { error: { code, message, request_id: '', retryable: false } }, 'api');
+}
+/** POST /v1/auth/device. */
+export async function startDeviceAuthorization(opts, clientName, signal) {
+    const path = '/v1/auth/device';
+    const r = await call(opts, path, { client_name: clientName }, signal);
+    if (r.status !== 200)
+        throw apiError(r.status, r.body, r.retryAfter, path);
+    const d = r.body;
+    if (!d ||
+        typeof d.device_code !== 'string' ||
+        !DEVICE_CODE.test(d.device_code) ||
+        typeof d.user_code !== 'string' ||
+        !USER_CODE.test(d.user_code) ||
+        typeof d.verification_uri_complete !== 'string' ||
+        !/^https?:\/\//.test(d.verification_uri_complete) ||
+        typeof d.expires_in !== 'number' ||
+        typeof d.interval !== 'number') {
+        throw new ShardfluxProtocolError(`POST ${path} answered without a device authorization`, r.status, 'api');
+    }
+    return d;
+}
+/** No answer: the connection failed or timed out, or something other than the API answered (a proxy's HTML page). */
+function transient(err) {
+    if (err instanceof TypeError && err.message === 'fetch failed')
+        return true;
+    return err instanceof Error && (err.name === 'TimeoutError' || err.name === 'ShardfluxProtocolError');
+}
+/**
+ * Polls POST /v1/auth/device/token until the session is issued (RFC 8628 §3.4, §3.5): waits `interval` seconds before
+ * each poll; a slow_down adds 5 s (or takes the server's longer interval); a connection failure or timeout doubles the
+ * interval (exponential backoff); 429 waits its Retry-After and 5xx the interval, while the request can still be
+ * approved. Stops on access_denied, expired_token and every other refusal (thrown as the API's error), and when the
+ * request's lifetime has passed.
+ */
+export async function waitForDeviceSession(opts, d, poll) {
+    const path = '/v1/auth/device/token';
+    const now = poll.now ?? Date.now;
+    const deadline = now() + d.expires_in * 1000 + EXPIRY_GRACE_MS;
+    const timeoutMs = poll.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
+    const unreachable = () => localError('expired_token', 'The sign-in request expired before Shardflux could be reached. Start again: shard auth login --browser');
+    let interval = Math.max(1, d.interval);
+    let wait = interval;
+    for (;;) {
+        await poll.sleep(wait * 1000);
+        if (poll.signal.aborted)
+            throw poll.signal.reason instanceof Error ? poll.signal.reason : new DOMException('Interrupted.', 'AbortError');
+        wait = interval;
+        let r;
+        try {
+            r = await call(opts, path, { device_code: d.device_code }, AbortSignal.any([poll.signal, AbortSignal.timeout(timeoutMs)]));
+        }
+        catch (err) {
+            if (poll.signal.aborted || !transient(err))
+                throw err;
+            // RFC 8628 §3.5: back off exponentially on connection timeouts.
+            interval *= 2;
+            wait = interval;
+            if (now() + wait * 1000 > deadline)
+                throw unreachable();
+            continue;
+        }
+        if (r.status === 200) {
+            const s = r.body;
+            if (!s || typeof s.session_token !== 'string' || !SESSION_TOKEN.test(s.session_token) || !s.user || typeof s.user.email !== 'string') {
+                throw new ShardfluxProtocolError(`POST ${path} answered 200 without a session`, 200, 'api');
+            }
+            return s;
+        }
+        const err = apiError(r.status, r.body, r.retryAfter, path);
+        const code = err instanceof ShardfluxApiError ? err.code : null;
+        if (code === 'authorization_pending')
+            continue;
+        if (code === 'slow_down') {
+            const given = err.details?.interval;
+            interval = Math.max(interval + SLOW_DOWN_STEP_SECONDS, typeof given === 'number' && Number.isFinite(given) ? given : 0);
+            wait = interval;
+            continue;
+        }
+        if (code === 'rate_limited' || r.status >= 500) {
+            const after = err instanceof ShardfluxApiError ? err.retryAfterSeconds : undefined;
+            wait = Math.max(interval, after ?? interval);
+            // Waiting past the request's lifetime cannot succeed: report the refusal now.
+            if (now() + wait * 1000 > deadline)
+                throw err;
+            continue;
+        }
+        throw err;
+    }
+}

package/dist/claude-cloud-login.js

@@ -2,7 +2,7 @@ import { isDeepStrictEqual } from 'node:util';
 import { ShardfluxApiError } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
 import { openUrl } from "./browser.js";
-import { attachTerminal, cellConnector, PtyOutputCursor } from "./agent-terminal.js";
+import { attachTerminal, cellConnector, PtyOutputCursor, workspaceAsleep } from "./agent-terminal.js";
 const NEED_TERMINAL = 'Claude sign-in needed. Run shard agents credentials login claude in a terminal.';
 const VERSION = '2.1.289';
 export function requireClaudeTerminal(ctx) {
@@ -107,7 +107,7 @@ export async function loginClaudeInWorkspace(ctx, ws) {
         const opened = new Set();
         const cursor = new PtyOutputCursor();
         let output = '';
-        const code = await attachTerminal({ io: ctx.io, signal: ctx.signal, wake: signal => ws.wake({ signal }), invalidate: () => { },
+        const code = await attachTerminal({ io: ctx.io, signal: ctx.signal, wake: signal => ws.wake({ signal }), asleep: () => workspaceAsleep(ws), invalidate: () => { },
             sleep: (ms, signal) => new Promise(resolve => {
                 const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
                 const timer = setTimeout(done, ms);

package/dist/codex-cloud.d.ts

@@ -0,0 +1,49 @@
+import type { CodexCloudTask } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+import type { Values } from './args.js';
+import type { Conversation } 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>;
+export declare function submitCloudInitialPrompt(ctx: Ctx, c: Conversation, prompt: string, workspaceKey: string): Promise<void>;
+/** 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 = {
+    state: string;
+    environment_id: string | null;
+    last_error: string | null;
+    workspace_id?: string;
+    generation?: string;
+};
+/**
+ * The account's Codex remote device, as a person needs to know it: missing or disabled (enable it), starting (wait),
+ * ready, or failed, stuck (starting for longer than CODEX_STARTING_LIMIT_MS) or attention (retry once).
+ */
+export type CodexHealth = 'missing' | 'disabled' | 'starting' | 'ready' | 'failed' | 'stuck' | 'attention';
+/** When a connector generation started: its UUIDv7 time. */
+export declare function generationStarted(generation: string | undefined): number | null;
+export declare function codexHealth(c: CodexConnectorView | null, workspaceState: string | null, now?: number): CodexHealth;
+/** The connector and the state of its workspace (failed, deleted when it is gone). Never wakes anything. */
+export declare function readCodexConnector(ctx: Ctx): Promise<{
+    connector: CodexConnectorView | null;
+    workspaceState: string | null;
+}>;
+/**
+ * Starts the remote device again, once: disable, wait until it is disabled (bounded), enable. One executor per account
+ * throughout. Used by Retry in setup and Settings; never called in a loop.
+ */
+export declare function restartCodexConnector(ctx: Ctx, timeoutMs?: number): Promise<CodexConnectorView>;
+export declare function ensureCodexCloud(ctx: Ctx): Promise<{
+    organization_id: string;
+    project_id: string;
+    workspace_id: string;
+    generation: string;
+    enabled: boolean;
+    state: "starting" | "ready" | "attention" | "disabling" | "disabled";
+    environment_id: string | null;
+    last_error: string | null;
+    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>;
+export declare const CODEX_CLOUD_HANDLERS: Record<string, Handler>;