@shardflux/cli 0.24.0 → 0.24.1

package/dist/codex-cloud.d.ts

@@ -1,4 +1,4 @@
-import type { CodexCloudTask } from '@shardflux/sdk';
+import type { CodexCloudTask, LocalCodexLogin } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
 import type { Values } from './args.js';
 import type { ModelChoice } from './agent-models.js';
@@ -15,6 +15,25 @@ export declare function printCloudThread(ctx: Ctx, c: Conversation, task: CodexC
  * 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;
+type ThreadAccount = NonNullable<CodexCloudTask['account']>;
+/**
+ * The line a client shows when the Codex app here would not open a thread of `account` (0.25.0+): it is signed out, or
+ * signed in to another account, and opening the thread there fails without saying why. It names the account to sign
+ * in as and the thread's web link.
+ */
+export declare function codexAppMismatchLine(account: ThreadAccount, login: LocalCodexLogin, url: string): string;
+/**
+ * After the active Codex account changes (0.25.0+): the Codex app's sign-in here and, when it is not that account, the
+ * line that says so (its new Cloud threads open in the app only once it signs in to that account). Null without the app.
+ */
+export declare function codexAppAccountNotice(ctx: Ctx, account: {
+    email: string | null;
+    label: string;
+    chatgpt_account_id?: string | null;
+}): Promise<{
+    login: LocalCodexLogin;
+    line: string | null;
+} | null>;
 /** 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 = {
@@ -23,12 +42,18 @@ export type CodexConnectorView = {
     last_error: string | null;
     workspace_id?: string;
     generation?: string;
+    reason?: string | null;
 };
 /**
  * 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).
+ * ready, failed, stuck (starting for longer than CODEX_STARTING_LIMIT_MS) or attention (retry once), or sign_in
+ * (0.25.0+): Codex Cloud refused the account's ChatGPT sign-in, so it waits for a new one (never restarted).
  */
-export type CodexHealth = 'missing' | 'disabled' | 'starting' | 'ready' | 'failed' | 'stuck' | 'attention';
+export type CodexHealth = 'missing' | 'disabled' | 'starting' | 'ready' | 'failed' | 'stuck' | 'attention' | 'sign_in';
+/** The connector's reason while Codex Cloud refuses the account's ChatGPT sign-in. */
+export declare const CODEX_SIGN_IN_REQUIRED = "codex_sign_in_required";
+/** What every client says when Codex Cloud needs a new ChatGPT sign-in (0.25.0+). */
+export declare const CODEX_SIGN_IN_LINE = "Your ChatGPT sign-in for Codex expired. Sign in again with codex login, then run shard agents credentials sync.";
 /** 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;
@@ -52,6 +77,7 @@ export declare function ensureCodexCloud(ctx: Ctx): Promise<{
     environment_id: string | null;
     last_error: string | null;
     last_seen_at: string | null;
+    reason: string | null;
 }>;
 export declare function launchCodexCloud(ctx: Ctx, values: Values, path: string, images?: readonly InitialImage[]): Promise<number>;
 /** A start whose carrying process said so in the last 45 s. */
@@ -60,3 +86,4 @@ export declare function openCodexConversation(ctx: Ctx, c: Conversation, history
 /** 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>;
+export {};

package/dist/codex-cloud.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
+import { ShardfluxApiError, codexAccountMatches, localCodexLogin } from '@shardflux/sdk';
 import { CodedError, UsageError } from "./errors.js";
 import { json } from "./format.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
@@ -50,20 +51,66 @@ export function cloudChatElsewhere(c, url) {
     return `${c.key} runs in Codex Cloud${c.state === 'needs_you' ? ' and is waiting for your answer' : ''}. Its chat opens in your browser: ${url}\n` +
         `Answer it from here: shard conversations send ${c.id} "<your answer>"\nWhere it stands: shard conversations get ${c.id}\n`;
 }
+/** An account as a person names it. */
+const who = (a) => a.email ?? a.label ?? 'its Codex account';
+/** The earlier threads of a Cloud task with their accounts (an API before 2026-10-15 lists only their ids). */
+const earlierThreads = (task) => (task.previous_thread_ids ?? []).map(id => ({ thread_id: id, url: threadLink({ thread_id: id }),
+    account: task.previous_threads?.find(t => t.thread_id === id)?.account ?? null }));
+/**
+ * The line a client shows when the Codex app here would not open a thread of `account` (0.25.0+): it is signed out, or
+ * signed in to another account, and opening the thread there fails without saying why. It names the account to sign
+ * in as and the thread's web link.
+ */
+export function codexAppMismatchLine(account, login, url) {
+    const target = who(account), sameEmail = !!login.email && !!account.email && login.email.toLowerCase() === account.email.toLowerCase();
+    if (login.signed_in && sameEmail)
+        return `This Codex thread belongs to another ChatGPT workspace of ${target} than the Codex app here. Switch the Codex app to that workspace, or open the thread in a browser signed in to it: ${url}`;
+    return `This Codex thread belongs to ${target}, ${login.signed_in ? `but the Codex app here is signed in as ${login.email ?? 'another account'}` : 'and the Codex app here is signed out'}. Sign in to the Codex app as ${target}, or open the thread in a browser signed in to that account: ${url}`;
+}
+/** The Codex app's sign-in here and, when it is not the thread's account, what to do: null without the Codex app. */
+async function appAccount(ctx, account, url, app) {
+    if (!app)
+        return { login: null, mismatch: null };
+    const login = await localCodexLogin(ctx.io.env ?? process.env);
+    const mismatch = account && codexAccountMatches(account, login) === false ? { line: codexAppMismatchLine(account, login, url), sign_in_as: who(account), web_url: url } : null;
+    return { login, mismatch };
+}
+/**
+ * After the active Codex account changes (0.25.0+): the Codex app's sign-in here and, when it is not that account, the
+ * line that says so (its new Cloud threads open in the app only once it signs in to that account). Null without the app.
+ */
+export async function codexAppAccountNotice(ctx, account) {
+    if (!codexAppHere(ctx.io.env))
+        return null;
+    const login = await localCodexLogin(ctx.io.env ?? process.env);
+    if (codexAccountMatches(account, login) !== false)
+        return { login, line: null };
+    const target = who(account), sameEmail = login.signed_in && !!login.email && !!account.email && login.email.toLowerCase() === account.email.toLowerCase();
+    const line = sameEmail ? `The Codex app here uses another ChatGPT workspace of ${target}: switch it to this account’s workspace to open its Cloud threads there.`
+        : `The Codex app here is ${login.signed_in ? `signed in as ${login.email ?? 'another account'}` : 'signed out'}: sign in to it as ${target} to open this account’s Cloud threads there.`;
+    return { login, line };
+}
 async function output(ctx, c, task, submitted = false, choice) {
-    const url = threadLink(task), app = codexAppHere(ctx.io.env);
+    const url = threadLink(task), app = codexAppHere(ctx.io.env), account = task.account ?? null;
     // model_choice (0.17.0+): an admitted thread's record keeps the model and effort only when Cloud started it with them.
     const applied = hasChoice(choice) ? await cloudChoiceApplied(ctx, c, choice) : true;
+    // account, codex_app_login and account_mismatch (0.25.0+): the Codex app opens a thread only while signed in to its account.
+    const { login, mismatch } = await appAccount(ctx, account, url, app);
     // codex_app and reply_command (0.23.0+): without the Codex app, the conversation is answered with that command.
     if (ctx.json) {
-        ctx.io.stdout.write(json({ conversation: c, cloud: task, url, previous_threads: (task.previous_thread_ids ?? []).map(id => ({ thread_id: id, url: threadLink({ thread_id: id }) })), codex_app: app, reply_command: ['shard', 'conversations', 'send', c.id, '<message>'], ...(submitted ? { initial_prompt: { submitted: true } } : {}), ...(hasChoice(choice) ? { model_choice: choiceReport(choice, applied) } : {}) }));
+        ctx.io.stdout.write(json({ conversation: c, cloud: task, url, account, previous_threads: earlierThreads(task), codex_app: app, codex_app_login: login, account_mismatch: mismatch, reply_command: ['shard', 'conversations', 'send', c.id, '<message>'], ...(submitted ? { initial_prompt: { submitted: true } } : {}), ...(hasChoice(choice) ? { model_choice: choiceReport(choice, applied) } : {}) }));
         return;
     }
     if (!applied)
         ctx.io.stderr.write(`${CHOICE_PENDING}\n`);
     ctx.io.stdout.write(`${c.key}\n${url}\n`);
-    for (const id of task.previous_thread_ids ?? [])
-        ctx.io.stdout.write(`Earlier history: https://chatgpt.com/local/${encodeURIComponent(id)}\n`);
+    for (const t of earlierThreads(task))
+        ctx.io.stdout.write(`Earlier history: ${t.url}${t.account ? ` (${who(t.account)})` : ''}\n`);
+    // Opening it in the Codex app would fail on another account: say which account opens it instead.
+    if (mismatch) {
+        ctx.io.stdout.write(`${mismatch.line}\n`);
+        return;
+    }
     await openCodexThread(task, ctx.io.env);
 }
 async function cloudChoiceApplied(ctx, c, choice) {
@@ -72,6 +119,10 @@ async function cloudChoiceApplied(ctx, c, choice) {
 }
 /** How long the account's Codex remote device may take to come up before it counts as stuck. */
 export const CODEX_STARTING_LIMIT_MS = 5 * 60_000;
+/** The connector's reason while Codex Cloud refuses the account's ChatGPT sign-in. */
+export const CODEX_SIGN_IN_REQUIRED = 'codex_sign_in_required';
+/** What every client says when Codex Cloud needs a new ChatGPT sign-in (0.25.0+). */
+export const CODEX_SIGN_IN_LINE = 'Your ChatGPT sign-in for Codex expired. Sign in again with codex login, then run shard agents credentials sync.';
 /** When a connector generation started: its UUIDv7 time. */
 export function generationStarted(generation) {
     const hex = generation?.replace(/-/g, '').slice(0, 12);
@@ -82,10 +133,13 @@ export function codexHealth(c, workspaceState, now = Date.now()) {
         return 'missing';
     if (c.state === 'disabled' || c.state === 'disabling')
         return 'disabled';
+    if (c.reason === CODEX_SIGN_IN_REQUIRED)
+        return 'sign_in';
     if (c.state === 'ready' && c.environment_id)
         return 'ready';
     const started = generationStarted(c.generation);
-    const late = started !== null && now - started > CODEX_STARTING_LIMIT_MS;
+    // A device that connected before and starts again (with a new sign-in) is starting however old its generation is.
+    const late = started !== null && now - started > CODEX_STARTING_LIMIT_MS && !(c.state === 'starting' && c.environment_id);
     // A new device reports attention while its executor is still connecting, and the API tries again every 10 s on its
     // own (staging: about 40 s after enable, ready 9 s later). Until the starting limit that is starting, not Retry.
     if (c.state === 'attention')
@@ -125,16 +179,36 @@ export async function restartCodexConnector(ctx, timeoutMs = 60_000) {
     }
     return await codex.enable({ signal: ctx.signal });
 }
+const signInRequired = () => new CodedError(CODEX_SIGN_IN_REQUIRED, CODEX_SIGN_IN_LINE, undefined, { reason: CODEX_SIGN_IN_REQUIRED });
 export async function ensureCodexCloud(ctx) {
-    await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME ?? ctx.io.env.USERPROFILE, redact: value => ctx.addSecret(value) });
-    // A remote device that failed or is stuck starting gets one new start; a starting or ready one is left alone.
+    const sync = () => syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME ?? ctx.io.env.USERPROFILE, redact: value => ctx.addSecret(value) });
     const { connector, workspaceState } = await readCodexConnector(ctx);
     const health = codexHealth(connector, workspaceState);
-    if (health === 'failed' || health === 'stuck' || health === 'attention')
-        await restartCodexConnector(ctx);
-    else
+    if (health === 'sign_in') {
+        // Codex Cloud refused the copied login (0.25.0+). This computer's login starts it again only if it is a different
+        // one; the same login means Codex itself needs a new sign-in first. Never a restart: the device keeps its threads.
+        const refused = (await ctx.cloud().agentCredentials.list()).find(row => row.app === 'codex')?.fingerprint ?? null;
+        const copied = (await sync()).find(row => row.app === 'codex')?.fingerprint ?? null;
+        if (!copied || copied === refused)
+            throw signInRequired();
         await ctx.cloud().codex.enable({ signal: ctx.signal });
-    return ctx.cloud().codex.waitConnector({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+    }
+    else {
+        await sync();
+        // A remote device that failed or is stuck starting gets one new start; a starting or ready one is left alone.
+        if (health === 'failed' || health === 'stuck' || health === 'attention')
+            await restartCodexConnector(ctx);
+        else
+            await ctx.cloud().codex.enable({ signal: ctx.signal });
+    }
+    try {
+        return await ctx.cloud().codex.waitConnector({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+    }
+    catch (error) {
+        if (error instanceof ShardfluxApiError && error.reason === CODEX_SIGN_IN_REQUIRED)
+            throw signInRequired();
+        throw error;
+    }
 }
 export async function launchCodexCloud(ctx, values, path, images = []) {
     if (values.in !== undefined && values.in !== 'codex-app')
@@ -207,7 +281,7 @@ export async function openCodexConversation(ctx, c, history) {
         const id = history === true ? ids[0] : history;
         if (!id || !ids.includes(id))
             throw new UsageError('This conversation has no matching earlier Cloud history.');
-        return output(ctx, c, { ...task, thread_id: id, desktop_url: null, web_url: null }, false).then(() => 0);
+        return output(ctx, c, { ...task, thread_id: id, desktop_url: null, web_url: null, account: task.previous_threads?.find(t => t.thread_id === id)?.account ?? null }, false).then(() => 0);
     }
     const local = localConversations(ctx)[c.id];
     if (local?.cloud_start && local.cloud_start.state !== 'active' && !c.ended_at) {

package/dist/conversation-commands.d.ts

@@ -1,4 +1,5 @@
 import type { Ctx, Handler } from './commands.js';
+import type { CellClient, ConversationPermission, ListeningPort, MessageAttachment, PermissionDecision } from '@shardflux/sdk';
 export declare function conversationClient(ctx: Ctx): import("@shardflux/sdk").Shardflux | import("@shardflux/sdk").ShardfluxAccount;
 /** Why a conversation needs you, as one line of at most `max` characters; undefined in other states (0.18.0+). */
 export declare function questionLine(c: {
@@ -9,5 +10,34 @@ export declare function questionLine(c: {
  * prompt names it; a name someone chose stays (0.21.1+). The menu bar's AgentNaming.isRawIdentifier rule. */
 export declare function displayTitle(c: {
     title: string;
+    title_short?: string | null;
 }): string;
+/**
+ * `--file <path>` (repeatable, 0.25.0+): files for a message, read whole and checked before anything is sent. Each one
+ * keeps its file name in the conversation's computer.
+ */
+export declare function readAttachments(paths: readonly string[]): Promise<MessageAttachment[]>;
+/** A permission request's command, path or URL as one line of at most `max` characters: its first line (0.25.0+). */
+export declare function detailLine(detail: string, max?: number): string;
+/** One permission request as a list row (0.25.0+): id, state, title, detail, and the decision once answered. */
+export declare function permissionLine(p: ConversationPermission): string;
+/** `shard conversations answer` words (0.25.0+): allow, always and deny, or the API's own decision names. */
+export declare const PERMISSION_DECISIONS: Readonly<Record<string, PermissionDecision>>;
+/** --pick values as a question's answers (0.25.0+): "<question>=<option>" names the question; a bare option answers
+ * the request's only question (repeated, a multi-select one's several options). `shard needs-you answer` passes the
+ * questions of a board item. */
+export declare function pickAnswers(p: Pick<ConversationPermission, 'questions'>, picks: readonly string[]): Record<string, string | string[]>;
+/** A listening port as `conversations get` prints it: the port, its program, then its URL once exposed, else where it
+ * listens ("5173  node  https://… (exposed)", "5432  postgres  127.0.0.1 only"). */
+export declare function portLine(p: ListeningPort): string;
+/** How much of the terminal's past `conversations watch` shows before the live output: its last 256 KiB. */
+export declare const WATCH_TAIL_BYTES: number;
+/**
+ * Streams a conversation's terminal read-only from its last WATCH_TAIL_BYTES until its session exits or ctx.signal
+ * aborts (Ctrl-C), writing the terminal's bytes to stdout as they arrive. Nothing is ever typed into it, and the attach is
+ * passive: it never wakes the computer or keeps it awake while the terminal is idle (reading the terminal's size first
+ * wakes a sleeping computer, as every cell call does unless --no-wake). A host without passive attach gets an ordinary
+ * read-only attach next, from the same byte.
+ */
+export declare function watchTerminal(ctx: Ctx, cell: CellClient, ptyId: string): Promise<number>;
 export declare const CONVERSATION_HANDLERS: Record<string, Handler>;

package/dist/conversation-commands.js

@@ -1,11 +1,38 @@
-import { out, str } from "./commands.js";
-import { UsageError } from "./errors.js";
+import { randomUUID } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { out, str, strs } from "./commands.js";
+import { CodedError, UsageError } from "./errors.js";
+import { MAX_ATTACHMENT_BYTES, MAX_ATTACHMENTS, PtyConnection, planAttachments } from '@shardflux/sdk';
 import { FilesMirror, humanBytes, listMirrorConversations, workspaceHub } from "./files-mirror.js";
+import { modelChoice } from "./agent-models.js";
+import { storedTitlePrefix } from "./client-settings.js";
+import { PtyOutputCursor, passiveUnavailable, sleepingAttach } from "./agent-terminal.js";
+import { progress } from "./progress.js";
+import { UUID } from "./args.js";
+import { findOrg } from "./account-scope.js";
 export function conversationClient(ctx) {
     const key = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
     const session = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || ctx.store.profile(ctx.apiUrl).session !== undefined;
     return key || !session ? ctx.cloud() : ctx.account();
 }
+/**
+ * The client and organization of `conversations list` and `feed` (0.25.0+). Without --org: the API key's project, or
+ * signed in without a key every project the person works in. --org acts as the signed-in person when there is a sign-in
+ * (an organization id, or a slug looked up among theirs); with only an API key it is the key's own organization.
+ */
+async function listScope(ctx, values) {
+    const org = str(values.org);
+    if (org === undefined)
+        return { client: conversationClient(ctx) };
+    if (ctx.sessionSource() !== null) {
+        const account = ctx.account();
+        return { client: account, organizationId: UUID.test(org) ? org : (await findOrg(account, org)).id };
+    }
+    if (!UUID.test(org))
+        throw new UsageError(`--org with an API key takes the organization id (got "${org}").`, 'or sign in to name organizations by slug: shard auth login');
+    return { client: ctx.cloud(), organizationId: org };
+}
 /** Why a conversation needs you, as one line of at most `max` characters; undefined in other states (0.18.0+). */
 export function questionLine(c, max = 100) {
     const text = c.state === 'needs_you' ? c.question?.replace(/\s+/g, ' ').trim() : undefined;
@@ -13,7 +40,156 @@ export function questionLine(c, max = 100) {
 }
 /** A conversation's title as people read it: "New conversation" while it is still named by its generated id, before a
  * prompt names it; a name someone chose stays (0.21.1+). The menu bar's AgentNaming.isRawIdentifier rule. */
-export function displayTitle(c) { return !c.title || /^(conv[-_])?[a-z0-9]{26}$/.test(c.title) ? 'New conversation' : c.title; }
+export function displayTitle(c) {
+    // The agent's own short name for it, once it has one (APIs from 0221; CLI 0.25.0+).
+    if (c.title_short?.trim())
+        return c.title_short.trim();
+    return !c.title || /^(conv[-_])?[a-z0-9]{26}$/.test(c.title) ? 'New conversation' : c.title;
+}
+/**
+ * `--file <path>` (repeatable, 0.25.0+): files for a message, read whole and checked before anything is sent. Each one
+ * keeps its file name in the conversation's computer.
+ */
+export async function readAttachments(paths) {
+    if (paths.length > MAX_ATTACHMENTS)
+        throw new UsageError(`Attach at most ${MAX_ATTACHMENTS} files to a message.`);
+    const files = [];
+    for (const path of paths) {
+        const handle = await open(path, 'r').catch((e) => { throw new UsageError(`--file: cannot read "${path}" (${e.code ?? e.message})`); });
+        try {
+            const info = await handle.stat();
+            if (!info.isFile())
+                throw new UsageError(`--file: "${path}" is not a file.`);
+            if (info.size > MAX_ATTACHMENT_BYTES)
+                throw new UsageError(`--file: "${path}" is larger than ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MiB.`);
+            files.push({ name: basename(path), data: await handle.readFile() });
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    return files;
+}
+/** The SDK's checks of a message with files (names, sizes, the text with its list), as usage errors before any request. */
+function checkMessage(text, files) {
+    try {
+        planAttachments(`conv_${'a'.repeat(26)}`, randomUUID(), text, files);
+    }
+    catch (e) {
+        if (e instanceof TypeError || e instanceof RangeError)
+            throw new UsageError(e.message);
+        throw e;
+    }
+}
+const sentLines = (r) => `${r.restored ? 'Restored\n' : ''}${(r.files ?? []).map(f => `Attached ${f.path}\n`).join('')}Message sent (${r.seq}).\n`;
+/** A permission request's command, path or URL as one line of at most `max` characters: its first line (0.25.0+). */
+export function detailLine(detail, max = 80) {
+    const line = detail.split('\n').find(l => l.trim())?.replace(/\s+/g, ' ').trim() ?? '';
+    return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+}
+/** One permission request as a list row (0.25.0+): id, state, title, detail, and the decision once answered. */
+export function permissionLine(p) { return `${p.id}\t${p.state}\t${p.title}\t${detailLine(p.detail)}${p.decision ? `\t${p.decision}` : ''}`; }
+/** `shard conversations answer` words (0.25.0+): allow, always and deny, or the API's own decision names. */
+export const PERMISSION_DECISIONS = { allow: 'allow_once', allow_once: 'allow_once', always: 'allow_always', allow_always: 'allow_always', deny: 'deny' };
+const ANSWERED = { allow_once: 'Allowed once', allow_always: 'Always allowed', deny: 'Denied' };
+const PERMISSION_STATES = ['pending', 'answered', 'canceled'];
+/** --pick values as a question's answers (0.25.0+): "<question>=<option>" names the question; a bare option answers
+ * the request's only question (repeated, a multi-select one's several options). `shard needs-you answer` passes the
+ * questions of a board item. */
+export function pickAnswers(p, picks) {
+    const questions = p.questions ?? [];
+    if (!questions.length)
+        throw new UsageError('This request is not a question: answer it with allow, always or deny.');
+    const answers = {};
+    for (const pick of picks) {
+        const named = questions.find(q => pick.startsWith(`${q.question}=`));
+        const q = named ?? (questions.length === 1 ? questions[0] : undefined);
+        if (!q)
+            throw new UsageError(`This request asks ${questions.length} questions: --pick "<question>=<option>", e.g. --pick "${questions[0].question}=${questions[0].options[0]?.label ?? '…'}".`);
+        const label = named ? pick.slice(q.question.length + 1) : pick;
+        if (!label.trim())
+            throw new UsageError(`--pick needs an option for "${q.question}".`);
+        (answers[q.question] ??= []).push(label);
+    }
+    for (const q of questions)
+        if (!answers[q.question])
+            throw new UsageError(`Pick an answer for "${q.question}" too.`);
+    return Object.fromEntries(Object.entries(answers).map(([k, v]) => [k, v.length === 1 ? v[0] : v]));
+}
+/** A listening port as `conversations get` prints it: the port, its program, then its URL once exposed, else where it
+ * listens ("5173  node  https://… (exposed)", "5432  postgres  127.0.0.1 only"). */
+export function portLine(p) {
+    const loopback = /^127\./.test(p.address) || p.address === '::1' || p.address === 'localhost';
+    const where = p.exposed ? `${p.url ?? p.address} (exposed)` : loopback ? `${p.address} only` : `${p.address} (not exposed)`;
+    return [String(p.port), p.process, where].filter(Boolean).join('  ');
+}
+/** How much of the terminal's past `conversations watch` shows before the live output: its last 256 KiB. */
+export const WATCH_TAIL_BYTES = 256 * 1024;
+/** Why a conversation has no terminal to watch (its `pty_id` is null), with the command that shows its output. */
+function noTerminal(c) {
+    if (c.route === 'codex-cloud')
+        return `Codex Cloud runs this conversation, so its output is in its Codex thread: open it with shard agents open ${c.id}.`;
+    if (c.route !== 'terminal')
+        return `This conversation runs without a terminal (route ${c.route}): its app shows its output, and shard conversations get ${c.id} shows its state.`;
+    if (c.ended_at)
+        return `This conversation has finished: shard conversations get ${c.id} shows its result, and shard conversations resume ${c.id} continues it.`;
+    return `This conversation's terminal is starting: shard conversations get ${c.id} shows its pty_id once it runs.`;
+}
+/**
+ * Streams a conversation's terminal read-only from its last WATCH_TAIL_BYTES until its session exits or ctx.signal
+ * aborts (Ctrl-C), writing the terminal's bytes to stdout as they arrive. Nothing is ever typed into it, and the attach is
+ * passive: it never wakes the computer or keeps it awake while the terminal is idle (reading the terminal's size first
+ * wakes a sleeping computer, as every cell call does unless --no-wake). A host without passive attach gets an ordinary
+ * read-only attach next, from the same byte.
+ */
+export async function watchTerminal(ctx, cell, ptyId) {
+    const session = await cell.pty.get(ptyId);
+    const cursor = new PtyOutputCursor();
+    cursor.offset = Math.max(0, session.output_size - WATCH_TAIL_BYTES);
+    let passive = true, wrote = false;
+    try {
+        for (;;) {
+            if (ctx.signal.aborted)
+                return 0;
+            let connection;
+            try {
+                connection = await PtyConnection.attach(cell, ptyId, cursor.offset, ctx.signal, { readOnly: true, ...(passive ? { passive: true } : {}) });
+                for await (const m of connection.messages()) {
+                    const bytes = cursor.consume(m);
+                    if (bytes?.length) {
+                        ctx.io.stdout.write(bytes);
+                        wrote = true;
+                    }
+                    if (m.type === 'exit')
+                        return 0;
+                }
+                return 0;
+            }
+            catch (error) {
+                if (ctx.signal.aborted)
+                    return 0;
+                if (passive && passiveUnavailable(error)) {
+                    passive = false;
+                    continue;
+                }
+                // The computer parked under the watch: the agent is idle, and watching never wakes it.
+                if (sleepingAttach(error)) {
+                    progress(ctx, `${wrote ? '\r\n' : ''}The conversation's computer is asleep; watching ended.`);
+                    return 0;
+                }
+                throw error;
+            }
+            finally {
+                await connection?.close();
+            }
+        }
+    }
+    finally {
+        // The terminal's own modes (colours, a hidden cursor) end with the watch.
+        if (wrote && ctx.io.stdout.isTTY)
+            ctx.io.stdout.write('\x1b[0m\x1b[?25h\r\n');
+    }
+}
 export const CONVERSATION_HANDLERS = {
     async 'conversations resume'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.resume(id, { signal: ctx.signal }); out(ctx, `${displayTitle(r.conversation)}: resumed.\n`, r); return 0; },
     async 'conversations reader'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.spaceReader(id, { signal: ctx.signal }); out(ctx, `${r.workspace.workspace_key}\n`, r); return 0; },
@@ -23,8 +199,12 @@ export const CONVERSATION_HANDLERS = {
         let cursor = str(values.cursor), next;
         if (cursor)
             seen.add(cursor);
+        const updatedAfter = str(values['updated-after']);
+        if (updatedAfter !== undefined && Number.isNaN(Date.parse(updatedAfter)))
+            throw new UsageError('--updated-after must be an RFC 3339 time, such as 2026-10-15T09:00:00Z.');
+        const { client, organizationId } = await listScope(ctx, values);
         do {
-            const page = await conversationClient(ctx).conversations.list({ projectId: str(values.project), state, parentId: str(values.parent), cursor, limit: values.limit ? Number(values.limit) : values.all ? 200 : undefined });
+            const page = await client.conversations.list({ projectId: str(values.project), organizationId, state, parentId: str(values.parent), updatedAfter, cursor, limit: values.limit ? Number(values.limit) : values.all ? 200 : undefined });
             data.push(...page.data);
             next = page.nextCursor;
             cursor = next ?? undefined;
@@ -35,14 +215,137 @@ export const CONVERSATION_HANDLERS = {
             }
         } while (values.all && cursor);
         // A conversation that needs you adds a fifth column: why (0.18.0+).
-        out(ctx, data.map(c => { const q = questionLine(c); return `${c.id}\t${displayTitle(c)}\t${c.state}\t${c.branch}${q ? `\t${q}` : ''}`; }).join('\n') + '\n', { data, nextCursor: next });
+        out(ctx, data.map(c => { const q = questionLine(c); return `${c.id}\t${displayTitle(c)}\t${c.state}\t${c.home ? 'home' : c.branch}${q ? `\t${q}` : ''}`; }).join('\n') + '\n', { data, nextCursor: next });
+        return 0;
+    },
+    // Each change on its own line as it happens, until interrupted: "<id>\t<title>\t<state>[\t<why>]", or with --json one
+    // object per line, {conversation, cursor} (the cursor resumes after it with --cursor). 0.25.0+.
+    async 'conversations feed'(ctx, values) {
+        const { client, organizationId } = await listScope(ctx, values);
+        let cursor = str(values.cursor);
+        for await (const c of client.conversations.watch({ projectId: str(values.project), organizationId, cursor, signal: ctx.signal, onCursor: next => { cursor = next; } })) {
+            const q = questionLine(c);
+            ctx.io.stdout.write(ctx.json ? JSON.stringify({ conversation: c, cursor }) + '\n' : `${c.id}\t${displayTitle(c)}\t${c.state}${q ? `\t${q}` : ''}\n`);
+        }
+        return 0;
+    },
+    async 'conversations get'(ctx, _values, [id]) {
+        const client = conversationClient(ctx), c = await client.conversations.get(id);
+        const q = questionLine(c, 200);
+        // needs_you with no question: its agent waits on permission requests; text output names them (0.25.0+). JSON stays the
+        // conversation. The lookup only adds to what get shows, so an API without permission requests still shows it.
+        const waits = !ctx.json && c.state === 'needs_you' && !q ? await client.conversations.permissions(c.id, { state: 'pending' }).then(p => p.data, () => []) : [];
+        // The ports processes listen on in its computer follow, one line each, once its guest reported them.
+        const ports = (c.listening_ports ?? []).map(p => `${portLine(p)}\n`).join('');
+        out(ctx, `${displayTitle(c)}\n${c.state}\n${c.home ? 'home' : c.branch}\n${q ? `${q}\n` : ''}${waits.map(p => `Waiting on: ${p.title}\n`).join('')}${ports}`, c);
+        return 0;
+    },
+    // Permission requests (0.25.0+): what the conversation's agent asked before a tool ran, oldest first; every state
+    // unless --state, --all reads every page as conversations list does.
+    async 'conversations permissions'(ctx, values, [id]) {
+        const state = str(values.state);
+        if (state !== undefined && !PERMISSION_STATES.includes(state))
+            throw new UsageError('--state must be pending, answered or canceled.');
+        const client = conversationClient(ctx), data = [], seen = new Set();
+        let cursor = str(values.cursor), next;
+        if (cursor)
+            seen.add(cursor);
+        do {
+            const page = await client.conversations.permissions(id, { state, cursor, limit: values.limit ? Number(values.limit) : values.all ? 200 : undefined });
+            data.push(...page.data);
+            next = page.nextCursor;
+            cursor = next ?? undefined;
+            if (values.all && cursor) {
+                if (seen.has(cursor) || seen.size >= 100)
+                    throw new UsageError('The permission request list repeated its cursor. Try again.');
+                seen.add(cursor);
+            }
+        } while (values.all && cursor);
+        out(ctx, data.map(p => `${permissionLine(p)}\n`).join(''), { data, nextCursor: next });
         return 0;
     },
-    async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); const q = questionLine(c, 200); out(ctx, `${displayTitle(c)}\n${c.state}\n${c.branch}\n${q ? `${q}\n` : ''}`, c); return 0; },
+    async 'conversations answer'(ctx, values, [id, permissionId, word]) {
+        const picks = strs(values.pick), client = conversationClient(ctx);
+        // The agent's question (0.25.0+): --pick names the answer, which the agent gets exactly as picked.
+        if (picks.length) {
+            if (word !== undefined)
+                throw new UsageError('Answer a question with --pick, or decline it with deny, not both.');
+            const p = await client.conversations.permission(id, permissionId), answers = pickAnswers(p, picks);
+            const r = await client.conversations.answerQuestion(id, permissionId, answers, { signal: ctx.signal });
+            out(ctx, `Answered: ${Object.values(r.permission.answers ?? answers).map(a => Array.isArray(a) ? a.join(', ') : a).join('; ')}\n`, r);
+            return 0;
+        }
+        const decision = word === undefined ? undefined : PERMISSION_DECISIONS[word.toLowerCase().replace(/-/g, '_')];
+        if (!decision)
+            throw new UsageError('Choose allow, always or deny (a question takes --pick <option>).');
+        const r = await client.conversations.answerPermission(id, permissionId, decision, { signal: ctx.signal });
+        out(ctx, `${ANSWERED[r.permission.decision ?? decision]}: ${r.permission.title}\n`, r);
+        return 0;
+    },
+    // Its terminal, live and read-only, from the conversation's pty_id; never typed into, never keeping the computer awake.
+    async 'conversations watch'(ctx, _values, [id]) {
+        if (ctx.json)
+            throw new UsageError(`conversations watch streams the terminal itself, so it has no --json form; shard agents logs ${id} --json returns its recent output.`);
+        const client = conversationClient(ctx), c = await client.conversations.get(id);
+        if (!c.pty_id)
+            throw new UsageError(noTerminal(c));
+        const ws = await client.workspaces.get(c.workspace_id);
+        if (ws.data.deleted_at)
+            throw new UsageError(`This conversation is saved: shard conversations resume ${c.id} continues it in a fresh VM.`);
+        const cell = ws.cell({ agentLabel: ctx.agentLabel, ...(ctx.wake ? {} : { wake: null }), transitionTimeoutMs: ctx.wakeTimeoutMs });
+        try {
+            progress(ctx, `Watching ${displayTitle(c)}, read-only. Ctrl-C stops.`);
+            return await watchTerminal(ctx, cell, c.pty_id);
+        }
+        finally {
+            cell.close();
+        }
+    },
     // A finished conversation whose VM was removed restores into a fresh one, then takes the message (APIs that do; 0.18.1+).
-    async 'conversations send'(ctx, _values, [id, text]) {
-        const r = await conversationClient(ctx).conversations.send(id, text, { signal: ctx.signal });
-        out(ctx, `${r.restored ? 'Restored\n' : ''}Message sent (${r.seq}).\n`, r);
+    // --file (0.25.0+): the files land in the conversation's computer before the message, which lists their paths.
+    async 'conversations send'(ctx, values, [id, ...words]) {
+        const files = await readAttachments(strs(values.file)), text = words.length ? words.join(' ') : undefined;
+        if (text === undefined && !files.length)
+            throw new UsageError('missing <text> for "shard conversations send"');
+        if (files.length)
+            checkMessage(text ?? '', files);
+        const r = await conversationClient(ctx).conversations.send(id, text ?? '', { signal: ctx.signal, ...(files.length ? { files } : {}) });
+        out(ctx, sentLines(r), r);
+        return 0;
+    },
+    /**
+     * A conversation started without a folder (0.25.0+): on the machine's home (--home), or in one of the project's
+     * repositories from the project hub. With --prompt its first message follows, with any --file.
+     */
+    async 'conversations start'(ctx, values) {
+        const home = values.home === true, repo = str(values.repo), branch = str(values.branch), prompt = str(values.prompt), title = str(values.title);
+        if (home && (repo !== undefined || branch !== undefined))
+            throw new UsageError('--home starts on your machine without a repository: leave out --repo and --branch.');
+        const app = str(values.app) ?? 'claude';
+        if (app !== 'claude' && app !== 'codex')
+            throw new UsageError('Choose --app claude or codex.');
+        const choice = modelChoice(values, app);
+        if (prompt !== undefined && !prompt.trim())
+            throw new UsageError('--prompt needs text.');
+        const files = await readAttachments(strs(values.file));
+        if (files.length && prompt === undefined)
+            throw new UsageError('--file goes with the first message: add --prompt.');
+        if (prompt !== undefined)
+            checkMessage(prompt, files);
+        const projectId = str(values.project) ?? ctx.store.profile(ctx.apiUrl).project_id, titlePrefix = storedTitlePrefix(ctx.store.dir);
+        const client = conversationClient(ctx);
+        const created = await client.conversations.create({ ...(projectId ? { projectId } : {}), harness: app, route: 'terminal', mode: 'new', ...(home ? { home: true } : {}),
+            ...(repo !== undefined ? { repoRemote: repo } : {}), ...(branch !== undefined ? { base: { branch } } : {}), ...(title !== undefined ? { title } : {}), ...choice, ...(titlePrefix !== undefined ? { titlePrefix } : {}) }, { idempotencyKey: randomUUID(), signal: ctx.signal });
+        const c = created.conversation;
+        let message;
+        try {
+            if (prompt !== undefined)
+                message = await client.conversations.send(c.id, prompt, { idempotencyKey: randomUUID(), signal: ctx.signal, ...(files.length ? { files } : {}) });
+        }
+        catch (e) {
+            throw new CodedError('initial_prompt_failed', `Started ${c.key} (${c.id}), but its first message was not sent: ${e instanceof Error ? e.message : String(e)}`, `shard conversations send ${c.id} "<message>"`, { conversation_id: c.id, workspace_key: c.key });
+        }
+        out(ctx, `${c.id}\t${c.key}\t${c.state}\n${message ? sentLines(message) : ''}`, { ...created, ...(message ? { message } : {}) });
         return 0;
     },
     async 'conversations wait'(ctx, values, [id]) {