@shardflux/cli 0.16.0 → 0.17.0

package/dist/t3-phone.d.ts

@@ -0,0 +1,17 @@
+import type { T3Link } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export interface T3PhoneLink {
+    link: T3Link;
+    /** The person's T3 Connect sign-in to approve, once: open `verification_uri`, confirm `user_code`. */
+    signIn?: {
+        verification_uri: string;
+        user_code: string;
+    };
+    /** No signed-in session here to start the sign-in with (`shard auth login` first). */
+    needsLogin?: boolean;
+}
+/**
+ * Links a workspace for the T3 app on the phone (0.17.0+). An API key links with its creator's sign-in; starting that
+ * sign-in takes the person's own session, so the sign-in comes from `shard`'s session when the key has none yet.
+ */
+export declare function t3PhoneLink(ctx: Ctx, workspaceId: string): Promise<T3PhoneLink>;

package/dist/t3-phone.js

@@ -0,0 +1,15 @@
+/**
+ * Links a workspace for the T3 app on the phone (0.17.0+). An API key links with its creator's sign-in; starting that
+ * sign-in takes the person's own session, so the sign-in comes from `shard`'s session when the key has none yet.
+ */
+export async function t3PhoneLink(ctx, workspaceId) {
+    const link = await ctx.cloud().t3.link(workspaceId);
+    if (link.status !== 'needs_sign_in')
+        return { link };
+    if (link.sign_in)
+        return { link, signIn: link.sign_in };
+    if (ctx.store.profile(ctx.apiUrl).session?.state !== 'active')
+        return { link, needsLogin: true };
+    const flow = await ctx.account().t3.signIn();
+    return { link, signIn: flow };
+}

package/dist/t3-thread-script.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What `shard agents new --in t3 --prompt…` runs inside the project VM in SSH mode (T3 Code 0.0.45, whose server runs in
+ * the VM). It takes its input on stdin (the prompt and the session it issues never appear in argv) and prints one JSON
+ * line. Everything goes through T3's own interfaces, the way T3's CLI does it (apps/server/src/cli/project.ts):
+ *  1. the T3 runtime T3 installs (`~/.t3/runtime/versions/<version>/t3`), installing it when the prewarm has not;
+ *  2. the running server (`~/.t3/userdata/server-runtime.json`, its pid alive and `/` answering), else
+ *     `t3 serve --host 127.0.0.1 --port <first free from 3773> --base-dir ~/.t3`, the command T3's SSH launch uses, so
+ *     the desktop reuses that server when it connects (packages/ssh/src/tunnel.ts);
+ *  3. a 5-minute admin session (`t3 auth session issue --json`), used for the calls below and revoked after;
+ *  4. the project (`GET /api/orchestration/snapshot`, else `project.create` for the checkout);
+ *  5. `thread.create` then `thread.turn.start` (`POST /api/orchestration/dispatch`) over loopback.
+ * Every exit prints one JSON line (a failed revoke is logged on stderr, never in place of the result), and the images
+ * the CLI wrote for the first message are removed on every path. A server it starts logs to ~/.shardflux/t3-serve.log.
+ * The model is the one asked for, else the provider's default in T3's own provider cache (`~/.t3/caches/<id>.json`),
+ * else T3's built-in default. An effort is sent as the provider option T3 reads (`effort` for Claude,
+ * `reasoningEffort` for Codex) when the model offers it, or when T3 has not described the model yet.
+ */
+export declare const T3_THREAD_SCRIPT: string;

package/dist/t3-thread-script.js

@@ -0,0 +1,245 @@
+/**
+ * What `shard agents new --in t3 --prompt…` runs inside the project VM in SSH mode (T3 Code 0.0.45, whose server runs in
+ * the VM). It takes its input on stdin (the prompt and the session it issues never appear in argv) and prints one JSON
+ * line. Everything goes through T3's own interfaces, the way T3's CLI does it (apps/server/src/cli/project.ts):
+ *  1. the T3 runtime T3 installs (`~/.t3/runtime/versions/<version>/t3`), installing it when the prewarm has not;
+ *  2. the running server (`~/.t3/userdata/server-runtime.json`, its pid alive and `/` answering), else
+ *     `t3 serve --host 127.0.0.1 --port <first free from 3773> --base-dir ~/.t3`, the command T3's SSH launch uses, so
+ *     the desktop reuses that server when it connects (packages/ssh/src/tunnel.ts);
+ *  3. a 5-minute admin session (`t3 auth session issue --json`), used for the calls below and revoked after;
+ *  4. the project (`GET /api/orchestration/snapshot`, else `project.create` for the checkout);
+ *  5. `thread.create` then `thread.turn.start` (`POST /api/orchestration/dispatch`) over loopback.
+ * Every exit prints one JSON line (a failed revoke is logged on stderr, never in place of the result), and the images
+ * the CLI wrote for the first message are removed on every path. A server it starts logs to ~/.shardflux/t3-serve.log.
+ * The model is the one asked for, else the provider's default in T3's own provider cache (`~/.t3/caches/<id>.json`),
+ * else T3's built-in default. An effort is sent as the provider option T3 reads (`effort` for Claude,
+ * `reasoningEffort` for Codex) when the model offers it, or when T3 has not described the model yet.
+ */
+export const T3_THREAD_SCRIPT = String.raw `import base64, json, os, socket, subprocess, sys, time, urllib.error, urllib.request, uuid
+cfg = json.load(sys.stdin)
+home = os.path.expanduser('~')
+base = os.path.expanduser(cfg.get('base') or '~/.t3')
+version = cfg['version']
+t3 = cfg.get('t3') or os.path.join(base, 'runtime', 'versions', version, 't3')
+out = {'ok': True, 'server_started': False}
+
+def remove_images():
+    for image in cfg.get('images') or []:
+        try: os.remove(image['path'])
+        except OSError: pass
+
+def done(ok, error=None, message=None, **extra):
+    remove_images()
+    out['ok'] = ok
+    if error: out['error'] = error
+    if message: out['message'] = message[:500]
+    out.update(extra)
+    sys.stdout.write(json.dumps(out) + '\n')
+    sys.exit(0 if ok else 1)
+
+def runtime_ready():
+    if cfg.get('t3'): return os.access(t3, os.X_OK)
+    try:
+        with open(os.path.join(os.path.dirname(t3), '.install-complete')) as f: marker = f.read().strip()
+    except OSError:
+        return False
+    return os.access(t3, os.X_OK) and marker == version
+
+if not runtime_ready():
+    # A prewarm that is still downloading holds the install lock; this installer then exits at once and the wait follows it.
+    if cfg.get('install_script'):
+        try:
+            subprocess.run(['sh', '-c', cfg['install_script']], stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=float(cfg.get('install_timeout', 600)))
+        except Exception as e:
+            done(False, 'runtime_not_installed', 'The T3 runtime did not install in the workspace: %s' % e)
+    deadline = time.time() + float(cfg.get('install_wait', 300))
+    while not runtime_ready() and time.time() < deadline: time.sleep(1)
+    if not runtime_ready(): done(False, 'runtime_not_installed', 'The T3 runtime did not install in the workspace.')
+
+opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+def get(url, timeout=3):
+    with opener.open(url, timeout=timeout) as r: return r.status, r.read()
+def ready(origin):
+    try:
+        status, _ = get(origin + '/')
+        return 200 <= status < 300
+    except Exception:
+        return False
+def alive(pid):
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+state_dir = os.path.join(base, 'userdata')
+def running_origin():
+    try:
+        with open(os.path.join(state_dir, 'server-runtime.json')) as f: runtime = json.load(f)
+        pid, origin = int(runtime['pid']), str(runtime['origin'])
+    except Exception:
+        return None
+    if not (origin.startswith('http://127.0.0.1:') or origin.startswith('http://localhost:')) or not alive(pid): return None
+    return origin if ready(origin) else None
+
+origin = running_origin()
+if origin is None:
+    port = None
+    for candidate in range(int(cfg.get('default_port', 3773)), int(cfg.get('default_port', 3773)) + 200):
+        probe = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        try:
+            probe.bind(('127.0.0.1', candidate))
+            port = candidate
+            break
+        except OSError:
+            continue
+        finally:
+            probe.close()
+    if port is None: done(False, 'server_not_ready', 'No free port for the T3 server.')
+    # Shardflux's own log stays out of T3's data directory.
+    log_dir = os.path.join(home, '.shardflux')
+    os.makedirs(log_dir, exist_ok=True)
+    log = open(os.path.join(log_dir, 't3-serve.log'), 'ab')
+    env = dict(os.environ, T3CODE_NO_BROWSER='1')
+    standin = cfg.get('standin_path')
+    if standin and os.access(standin, os.X_OK): env['T3CODE_CLOUDFLARED_PATH'] = standin
+    server = subprocess.Popen(['nohup', t3, 'serve', '--host', '127.0.0.1', '--port', str(port), '--base-dir', base],
+                              stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT, env=env, cwd=home, start_new_session=True, close_fds=True)
+    out['server_started'] = True
+    origin = 'http://127.0.0.1:%d' % port
+    deadline = time.time() + float(cfg.get('start_wait', 120))
+    while not ready(origin):
+        if server.poll() is not None or time.time() > deadline: done(False, 'server_not_ready', 'The T3 server in the workspace did not start.')
+        time.sleep(0.25)
+out['origin'] = origin
+
+try:
+    _, raw = get(origin + '/.well-known/t3/environment', timeout=10)
+    descriptor = json.loads(raw)
+except Exception as e:
+    done(False, 'server_not_ready', 'The T3 server did not describe itself: %s' % e)
+out['server_version'] = descriptor.get('serverVersion')
+protocol = descriptor.get('orchestrationProtocolVersion', 1)
+out['protocol'] = protocol
+if protocol != 1:
+    done(False, 'version_unsupported', 'T3 %s in the workspace uses orchestration protocol %s.' % (descriptor.get('serverVersion'), protocol))
+
+try:
+    issued = subprocess.run([t3, 'auth', 'session', 'issue', '--base-dir', base, '--ttl', '5m', '--label', 'Shardflux thread start', '--json'],
+                            stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=float(cfg.get('issue_timeout', 60)))
+except Exception as e:
+    done(False, 'session_not_issued', 'T3 issued no session: %s' % e)
+try:
+    session = json.loads(issued.stdout)
+    token, session_id = session['token'], session.get('sessionId')
+except Exception:
+    done(False, 'session_not_issued', (issued.stderr or 'T3 issued no session').strip())
+
+def call(method, path, body=None):
+    data = json.dumps(body).encode() if body is not None else None
+    request = urllib.request.Request(origin + path, data=data, method=method,
+                                     headers={'authorization': 'Bearer ' + token, 'content-type': 'application/json', 'accept': 'application/json'})
+    try:
+        with opener.open(request, timeout=60) as r: status, raw = r.status, r.read()
+    except urllib.error.HTTPError as e:
+        status, raw = e.code, e.read()
+    try:
+        parsed = json.loads(raw) if raw else None
+    except Exception:
+        parsed = None
+    if not 200 <= status < 300:
+        tag = parsed.get('_tag') if isinstance(parsed, dict) else None
+        reason = parsed.get('reason') if isinstance(parsed, dict) else None
+        detail = ' '.join(str(v) for v in (tag, reason) if v)
+        done(False, 'dispatch_failed', 'T3 answered %s %s with %s%s.' % (method, path, status, ' ' + detail if detail else ''), status=status, tag=tag, reason=reason)
+    return parsed
+
+def now():
+    return time.strftime('%Y-%m-%dT%H:%M:%S', time.gmtime()) + '.%03dZ' % (int(time.time() * 1000) % 1000)
+
+def provider_models(instance):
+    try:
+        with open(os.path.join(base, 'caches', instance + '.json')) as f: provider = json.load(f)
+        models = provider.get('models')
+        return models if isinstance(models, list) and models else None
+    except Exception:
+        return None
+
+try:
+    snapshot = call('GET', '/api/orchestration/snapshot')
+    root = os.path.realpath(cfg['project_path']).rstrip('/') or '/'
+    project = next((p for p in snapshot.get('projects', []) if p.get('deletedAt') is None and p.get('workspaceRoot') == root), None)
+    if project is None:
+        project_id = str(uuid.uuid4())
+        call('POST', '/api/orchestration/dispatch', {'type': 'project.create', 'commandId': str(uuid.uuid4()), 'projectId': project_id,
+             'title': os.path.basename(root) or 'project', 'workspaceRoot': root, 'createdAt': now()})
+        out['project_created'] = True
+    else:
+        project_id = project['id']
+        out['project_created'] = False
+    out['project_id'] = project_id
+
+    instance = 'codex' if cfg['app'] == 'codex' else 'claudeAgent'
+    option_id = 'reasoningEffort' if cfg['app'] == 'codex' else 'effort'
+    models = provider_models(instance)
+    # A server started just now describes its providers within seconds of starting.
+    wait_until = time.time() + float(cfg.get('models_wait', 10))
+    while models is None and out['server_started'] and time.time() < wait_until:
+        time.sleep(0.5)
+        models = provider_models(instance)
+    model = cfg.get('model')
+    described = None
+    if models:
+        if model:
+            family = [m for m in models if cfg['app'] == 'claude' and model in ('fable', 'opus', 'sonnet', 'haiku') and str(m.get('slug', '')).startswith('claude-%s-' % model)]
+            described = next((m for m in family if not m.get('isLegacy')), None) or (family[0] if family else None)
+            described = described or next((m for m in models if m.get('slug') == model or model in (m.get('aliases') or [])), None)
+            if described is None:
+                done(False, 'model_unavailable', 'T3 in the workspace has no %s model %s.' % (cfg['app'], model), models=[m.get('slug') for m in models if not m.get('isLegacy')])
+            model = described['slug']
+        else:
+            described = next((m for m in models if m.get('isDefault')), None) or next((m for m in models if not m.get('isLegacy')), None)
+            model = described['slug'] if described else None
+    if not model: model = cfg['default_model']
+    effort = cfg.get('effort')
+    if effort and described is not None:
+        descriptors = ((described.get('capabilities') or {}).get('optionDescriptors') or [])
+        option = next((d for d in descriptors if d.get('id') == option_id), None)
+        if option is None or effort not in [o.get('id') for o in option.get('options') or []]: effort = None
+    selection = {'instanceId': instance, 'model': model}
+    if effort: selection['options'] = [{'id': option_id, 'value': effort}]
+    out['model'] = model
+    out['effort'] = effort or None
+    out['instance_id'] = instance
+
+    # Images the CLI wrote into the VM go inline (T3 0.0.45 UploadChatImageAttachment: dataUrl); T3 stores its own copy.
+    attachments = []
+    for image in cfg.get('images') or []:
+        with open(image['path'], 'rb') as f: data = f.read()
+        attachments.append({'type': 'image', 'name': image['name'], 'mimeType': image['mime'], 'sizeBytes': len(data),
+                            'dataUrl': 'data:%s;base64,%s' % (image['mime'], base64.b64encode(data).decode())})
+    out['attachments'] = len(attachments)
+
+    thread_id = str(uuid.uuid4())
+    created_at = now()
+    call('POST', '/api/orchestration/dispatch', {'type': 'thread.create', 'commandId': str(uuid.uuid4()), 'threadId': thread_id, 'projectId': project_id,
+         'title': cfg['title'], 'modelSelection': selection, 'runtimeMode': cfg.get('runtime_mode', 'full-access'), 'interactionMode': 'default',
+         'branch': None, 'worktreePath': None, 'createdAt': created_at})
+    out['thread_id'] = thread_id
+    started = call('POST', '/api/orchestration/dispatch', {'type': 'thread.turn.start', 'commandId': str(uuid.uuid4()), 'threadId': thread_id,
+         'message': {'messageId': str(uuid.uuid4()), 'role': 'user', 'text': cfg['prompt'], 'attachments': attachments},
+         'modelSelection': selection, 'titleSeed': cfg['title'], 'runtimeMode': cfg.get('runtime_mode', 'full-access'), 'interactionMode': 'default', 'createdAt': now()})
+    out['sequence'] = (started or {}).get('sequence')
+except Exception as e:
+    # A connection that drops mid-call still reports what exists (thread_id when thread.create got through).
+    done(False, 'dispatch_failed', 'T3 did not answer: %s' % e)
+finally:
+    remove_images()
+    if session_id:
+        try:
+            subprocess.run([t3, 'auth', 'session', 'revoke', session_id, '--base-dir', base], stdin=subprocess.DEVNULL, capture_output=True, timeout=float(cfg.get('revoke_timeout', 60)))
+        except Exception as e:
+            # The session expires by itself in 5 minutes; the thread (if made) is still reported.
+            sys.stderr.write('t3 session revoke failed: %s\n' % e)
+            out['revoke_failed'] = True
+done(True)
+`;

package/dist/terminal-onboarding.d.ts

@@ -0,0 +1,11 @@
+import type { Ctx, Handler } from './commands.js';
+import type { Values } from './args.js';
+import { onboardingReport } from './onboarding.js';
+export interface OnboardingDeps {
+    handlers?: Record<string, Handler>;
+    report?: typeof onboardingReport;
+    startHelper?: () => void;
+    loginCodex?: (ctx: Ctx) => Promise<void>;
+}
+/** Linux's first run orchestrates the same auth, setup and live inspection used by the Mac onboarding. */
+export declare function terminalOnboarding(ctx: Ctx, values: Values, deps?: OnboardingDeps): Promise<number>;

package/dist/terminal-onboarding.js

@@ -0,0 +1,75 @@
+import { spawn } from 'node:child_process';
+import { ACCOUNT_HANDLERS } from "./account-commands.js";
+import { AGENT_CREDENTIAL_HANDLERS } from "./agent-credentials.js";
+import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
+import { foundApps, onboardingReport, parseApps } from "./onboarding.js";
+import { requireTermsAcceptance, showLegalNotice } from "./legal.js";
+import { json } from "./format.js";
+import { UsageError } from "./errors.js";
+const handlers = { ...ACCOUNT_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...CODEX_CLOUD_HANDLERS };
+async function loginCodex(ctx) {
+    const child = spawn('codex', ['login', ...(!ctx.io.env.DISPLAY && !ctx.io.env.WAYLAND_DISPLAY ? ['--device-auth'] : [])], { env: ctx.io.env, stdio: 'inherit', signal: ctx.signal });
+    await new Promise((resolve, reject) => {
+        child.once('error', () => reject(new UsageError('Install the Codex CLI, then run codex login and shard.')));
+        child.once('exit', code => code === 0 ? resolve() : reject(new UsageError('Finish codex login, then run shard again.')));
+    });
+}
+/** Linux's first run orchestrates the same auth, setup and live inspection used by the Mac onboarding. */
+export async function terminalOnboarding(ctx, values, deps = {}) {
+    const commands = deps.handlers ?? handlers, report = deps.report ?? onboardingReport;
+    if (ctx.sessionSource() === null) {
+        ctx.io.stdout.write('Sign in to Shardflux\n');
+        if (!ctx.input.interactive) {
+            showLegalNotice(ctx);
+            ctx.io.stdout.write('Run shard in a terminal, or shard auth login --browser followed by shard setup.\n');
+            return 0;
+        }
+        await requireTermsAcceptance(ctx, values);
+        await commands['auth login'](ctx, { browser: true, open: !!(ctx.io.env.DISPLAY || ctx.io.env.WAYLAND_DISPLAY) }, []);
+    }
+    // Setup creates/reuses the project key. --inspect below is the live source of connection status.
+    try {
+        ctx.apiKey();
+    }
+    catch {
+        await commands.setup(ctx, { codex: false }, []);
+    }
+    deps.startHelper?.();
+    let apps = parseApps(values.apps) ?? await foundApps(ctx.io.env);
+    if (ctx.input.interactive && values.apps === undefined) {
+        const selected = (await ctx.input.answer(`Connect Claude, Codex or both? [${apps.join(',') || 'both'}] `))?.trim().toLowerCase();
+        apps = parseApps(selected === 'both' ? 'claude,codex' : selected || (apps.length ? apps : 'claude,codex'));
+    }
+    const inspect = { ...values, apps: apps.join(','), connect: true };
+    let state = await report(ctx, inspect);
+    for (const connection of state.connections.filter(c => c.picked && c.state === 'action')) {
+        const argv = connection.action?.command;
+        if (!argv || !ctx.input.interactive)
+            continue;
+        ctx.io.stdout.write(`${connection.action.title}\n`);
+        if (argv[0] === 'codex')
+            await (deps.loginCodex ?? loginCodex)(ctx);
+        else {
+            // These are the existing onboarding action commands, not a second implementation of sign-in.
+            const command = argv.slice(1, 4).join(' ');
+            if (command === 'agents credentials login')
+                await commands[command](ctx, {}, ['claude']);
+            else if (command === 'agents codex enable')
+                await commands[command](ctx, {}, []);
+            else if (argv[1] === 'setup')
+                await commands.setup(ctx, { ...inspect, inspect: true, 'retry-codex': true }, []);
+        }
+    }
+    state = await report(ctx, inspect);
+    if (ctx.json)
+        ctx.io.stdout.write(json({ onboarding: state, next: 'shard ./' }));
+    else {
+        for (const c of state.connections.filter(c => c.id === 'account' || c.picked))
+            ctx.io.stdout.write(`${c.id}: ${c.fact}${c.action?.command && c.state !== 'verified' ? ` Run ${c.action.command.join(' ')}.` : ''}\n`);
+        if (state.ready)
+            ctx.io.stdout.write('Ready. Run shard ./ in your project.\n');
+        else
+            ctx.io.stdout.write('Finish the connection above, then run shard again.\n');
+    }
+    return state.ready ? 0 : 1;
+}

package/dist/thread-on-computer.d.ts

@@ -1,8 +1,8 @@
 import type { Ctx, Handler } from './commands.js';
 import type { Values } from './args.js';
 import type { Conversation, Harness } from './conversations.js';
-/** A conversation still bound to its computer: not done, archived or ended. */
-export declare const activeConversation: (c: Pick<Conversation, "state" | "ended_at">) => boolean;
+/** A conversation still bound to its computer: not ended, archived or discarded (a settled `done` turn still is). */
+export declare const activeConversation: (c: Pick<Conversation, "state" | "ended_at" | "route" | "landed">) => boolean;
 export interface ComputerThread {
     id: string;
     key: string;

package/dist/thread-on-computer.js

@@ -1,3 +1,4 @@
+import { linuxTerminalSession } from "./linux-terminal.js";
 // A new Claude or Codex thread on an existing conversation's computer (0.16.0+): `shard agents new --on <ref>`,
 // `shard ./ --on <ref>` and `shard agents computers`. The thread joins that VM as a worker (its own branch and
 // worktree, sharing the VM's packages, caches, services, ports and files) or, with --review, as a read-only Claude
@@ -11,16 +12,17 @@ import { AgentStateStore } from "./agent-state.js";
 import { normalizeRemote, projectIdentity } from "./project-identity.js";
 import { progress } from "./progress.js";
 import { conversationClient } from "./conversation-commands.js";
-import { conversationName, conversationWorkspace, getConversation, listConversations, localConversations, rememberConversation, validateConversation, waitThreadReady } from "./conversations.js";
+import { conversationEnded, conversationName, conversationWorkspace, getConversation, listConversations, localConversations, rememberConversation, validateConversation, waitThreadReady } from "./conversations.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
 import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
 import { promptWithImages, readInitialImages, readInitialPrompt, uploadInitialImages } from "./initial-prompt.js";
 import { recordSeedSnapshot } from "./files-mirror.js";
 import { ensureCodexCloud, printCloudThread, submitCloudInitialPrompt } from "./codex-cloud.js";
+import { modelChoice } from "./agent-models.js";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const SHA = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
-/** A conversation still bound to its computer: not done, archived or ended. */
-export const activeConversation = (c) => c.state !== 'done' && c.state !== 'archived' && !c.ended_at;
+/** A conversation still bound to its computer: not ended, archived or discarded (a settled `done` turn still is). */
+export const activeConversation = (c) => !conversationEnded(c);
 /** The project's conversations: its repository's, or (for a folder without a remote) the ones started from it. */
 export function projectConversations(ctx, all, folder) {
     const project = projectIdentity(folder), remote = project.remote ?? `file://${project.folder}`, records = localConversations(ctx);
@@ -135,9 +137,11 @@ export async function startThreadOn(ctx, values, path, explicitApp) {
     if (chosen !== undefined && chosen !== 'claude' && chosen !== 'codex')
         throw new UsageError('--app must be claude or codex');
     const app = chosen ?? store.app(projectKey);
+    const nativeCodex = app === 'codex' && linuxTerminalSession(ctx, values);
     const review = values.review === true;
     if (review && app === 'codex')
         throw new UsageError('--review starts a read-only Claude reviewer. A Codex thread on a computer works on its own branch; omit --review.');
+    const choice = modelChoice(values, app);
     const name = str(values.name);
     if (name !== undefined && !/^[a-z0-9][a-z0-9-]{0,47}$/.test(name))
         throw new UsageError('--name must match ^[a-z0-9][a-z0-9-]{0,47}$');
@@ -151,6 +155,8 @@ export async function startThreadOn(ctx, values, path, explicitApp) {
         if (!ctx.json && values.detach !== true && (!ctx.io.stdin.isTTY || !ctx.io.stdin.setRawMode))
             throw new UsageError('agent terminal requires a TTY; add --json to start it detached');
     }
+    else if (nativeCodex)
+        await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
     else
         await ensureCodexCloud(ctx);
     progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} on the computer with ${target.title || target.key}…`);
@@ -159,12 +165,12 @@ export async function startThreadOn(ctx, values, path, explicitApp) {
     const baseBranch = target.base_branch ?? undefined;
     await uploadInitialImages(ws.cell(), images, ctx.signal);
     const response = await conversationClient(ctx).conversations.create({ projectId: target.project_id, repoRemote: target.repo_remote ?? ws.labels.repo_remote ?? '',
-        harness: app, route: app === 'codex' ? 'codex-cloud' : 'terminal', mode: 'join', parentId: target.id, ...(review ? { joinMode: 'reviewer' } : {}),
-        base: { commit, ...(baseBranch ? { branch: baseBranch } : {}) }, ...(name ? { name } : {}) }, { idempotencyKey: randomUUID(), signal: ctx.signal });
+        harness: app, route: app === 'codex' && !nativeCodex ? 'codex-cloud' : 'terminal', mode: 'join', parentId: target.id, ...(review ? { joinMode: 'reviewer' } : {}),
+        base: { commit, ...(baseBranch ? { branch: baseBranch } : {}) }, ...(name ? { name } : {}), ...choice }, { idempotencyKey: randomUUID(), signal: ctx.signal });
     let c = validateConversation({ ...response.conversation, restore: response.restore });
     rememberConversation(ctx, c, project.folder, false, baseBranch);
     store.save(projectKey, app);
-    if (app === 'codex') {
+    if (app === 'codex' && !nativeCodex) {
         try {
             await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-${c.id}`, signal: ctx.signal });
         }
@@ -177,7 +183,7 @@ export async function startThreadOn(ctx, values, path, explicitApp) {
         await recordSeedSnapshot(ws, c, ctx.signal);
         if (initialPrompt !== undefined)
             await submitCloudInitialPrompt(ctx, c, initialPrompt, ws.key);
-        await printCloudThread(ctx, c, task, initialPrompt !== undefined);
+        await printCloudThread(ctx, c, task, initialPrompt !== undefined, choice);
         return 0;
     }
     // The computer's guest prepares the worktree and starts the harness; the terminal attaches to that session.

package/dist/update.d.ts

@@ -59,5 +59,5 @@ export declare function update(ctx: Ctx, values: Record<string, unknown>, deps?:
 export declare function recordInstall(dir: string, runtime: Runtime, distribution: {
     package: string;
     version: string;
-}): void;
+}, env?: NodeJS.ProcessEnv): void;
 export declare const UPDATE_HANDLERS: Record<string, Handler>;

package/dist/update.js

@@ -286,12 +286,23 @@ async function refreshMenubar(ctx, menubar, runtime, run, env) {
     return after?.version && after.version !== before.version ? { status: 'restarted', version: after.version } : { status: 'current' };
 }
 /** Records where `shard` runs, for the menu bar's update button. Written on macOS, only when it changed. */
-export function recordInstall(dir, runtime, distribution) {
+export function recordInstall(dir, runtime, distribution, env = {}) {
     let script = runtime.script;
     try {
         script = realpathSync(script);
     }
     catch { /* keep the path */ }
+    // A global install (npm, pnpm, bun, Volta) is what the menu bar runs and updates. A run from a source checkout, a
+    // project's node_modules or npx never replaces a recorded install that still exists, so a one-off run cannot point
+    // the menu bar (and its update button) at it. SHARDFLUX_RECORD_INSTALL=1 records any run (menu bar development).
+    if (env.SHARDFLUX_RECORD_INSTALL !== '1' && !['npm', 'pnpm', 'bun', 'volta'].includes(detectInstall(script, distribution.package).manager)) {
+        try {
+            const recorded = JSON.parse(readFileSync(join(dir, INSTALL_FILE), 'utf8')).script;
+            if (typeof recorded === 'string' && recorded !== script && existsSync(recorded))
+                return;
+        }
+        catch { /* nothing recorded yet: this run is the best there is */ }
+    }
     // The app this CLI's npm package carries (0.15.2+): the menu bar compares itself with it and swaps itself in.
     let menubarApp = packagedAppPath();
     try {

package/dist/worktree-twin-engine.d.ts

@@ -56,19 +56,46 @@ export interface EngineDeps {
     hub?: string;
     vmTmp?: string;
     quietMs?: number;
+    /**
+     * Long-polls the conversation's next finished turn after `after` (RFC 3339): the turn's conversation and report time,
+     * null when the wait timed out. Throws TurnWaitUnsupported when the API has no turn waits.
+     */
+    waitTurn?(c: TwinConversation, after: string, signal: AbortSignal): Promise<{
+        conversation: TwinConversation;
+        reported_at: string;
+    } | null | 'ended'>;
 }
 /** A turn ended with committed work only; the agent is not asking anything. */
 export declare function finished(c: TwinConversation, agents: TwinAgent[]): TwinAgent | 'state' | null;
 export declare function eligible(c: TwinConversation, ledger: TwinLedger, now: number): boolean;
 export declare function conflictMessage(into: string, files: string[]): string;
+type Ready = {
+    c: TwinConversation;
+    record: LocalConversation;
+    mode: Exclude<LandingMode, 'off'>;
+    agent: TwinAgent | null;
+    at: number;
+};
+/** Refused by an API without turn waits (POST /wait with turn_after, 422): the twin polls instead. */
+export declare class TurnWaitUnsupported extends Error {
+}
 export declare class TwinEngine {
     #private;
     constructor(deps: EngineDeps);
-    /** One pass over every project with a local conversation; returns the suggested wait before the next. */
+    /** Resolves when a pushed turn is waiting to land (the loop's sleep ends at once). */
+    pushed(): Promise<void>;
+    /** Stops every turn wait. */
+    stop(): void;
+    /**
+     * One pass; returns the suggested wait before the next. Turns pushed by the waits land first, without a listing;
+     * otherwise (and at least every 15 s, or every second when the API has no turn waits) every project is listed.
+     */
     tick(signal?: AbortSignal): Promise<number>;
     /** Back online or awake: every conversation's retry backoff is cleared, so the next pass tries all of them. */
     resetBackoff(): void;
     landOne(c: TwinConversation, record: LocalConversation, mode: Exclude<LandingMode, 'off'>, agent: TwinAgent | null, signal?: AbortSignal): Promise<number | undefined>;
+    /** Several finished conversations for one branch: merged in their VMs at once, the files written once. */
+    landBatch(items: Ready[], signal?: AbortSignal): Promise<number | undefined>;
 }
 export interface LoopDeps {
     tick(signal: AbortSignal): Promise<number>;
@@ -81,6 +108,8 @@ export interface LoopDeps {
     network(): string;
     /** Whether the API host answers now (a TCP connect, no request). */
     reachable(): Promise<boolean>;
+    /** Resolves when a pushed turn waits to land: the loop's sleep ends at once. */
+    kicked?(): Promise<void>;
     log(line: string): void;
 }
 /**
@@ -93,3 +122,4 @@ export declare function runTwinLoop(deps: LoopDeps, signal: AbortSignal): Promis
 /** The device helper's twin. Nothing here asks the user anything. */
 export declare function runWorktreeTwin(ctx: Ctx, device: string, signal: AbortSignal): Promise<void>;
 export declare const TWIN_HANDLERS: Record<string, Handler>;
+export {};