@shardflux/cli 0.24.0 → 0.25.0

package/dist/board-commands.js

@@ -0,0 +1,412 @@
+import { out, principal, str, strs } from "./commands.js";
+import { detailLine, pickAnswers } from "./conversation-commands.js";
+import { NotFoundError, UsageError } from "./errors.js";
+import { time } from "./format.js";
+import { progress } from "./progress.js";
+import { landDeps, landTask, landedText } from "./land.js";
+const BUCKETS = ['now', 'next', 'later'];
+const BUCKET_TITLES = { now: 'Now', next: 'Next', later: 'Later' };
+const MODES = ['ask', 'routine', 'trusted'];
+/** The board's client: the project API key's. */
+const boardClient = (ctx) => ctx.cloud();
+const oneLine = (s, max) => {
+    const line = s.replace(/\s+/g, ' ').trim();
+    return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+};
+/** A task as people read it: its title once it has one, else your words, on one line of at most `max` characters. */
+export function taskLabel(t, max = 80) {
+    return oneLine(t.title?.trim() || t.text, max);
+}
+/** Why a task waits to start, or what a working one does now: "Getting its computer ready", "Fixing the login cookie". */
+function stateNote(t, max) {
+    const note = t.waiting?.message.trim() || (t.state === 'working' ? t.activity?.trim() : '') || '';
+    return note ? ` (${oneLine(note, max)})` : '';
+}
+/**
+ * One task as `shard board` lists it: id, state (with why it waits to start, "queued (Getting its computer ready)", or
+ * what it does now, "working (Fixing the login cookie)"), title or words (a follow-up ↳, a suggestion marked), project.
+ */
+export function taskLine(t) {
+    const state = `${t.state}${stateNote(t, 60)}`;
+    const label = `${t.parent_task_id ? '↳ ' : ''}${taskLabel(t)}${t.suggested ? ' (suggested)' : ''}`;
+    return `${t.id}\t${state}\t${label}\t${t.project_id}${t.home ? ' (home)' : ''}`;
+}
+/** One item that waits on you: its id, what is asked, then the command, the suggested answers or the branch behind it. */
+export function needsLine(n) {
+    const detail = n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.join(' / ') : n.land ? n.land.branch : '';
+    return `${n.id}\t${oneLine(n.ask, 100)}${detail ? `\t${detail}` : ''}`;
+}
+/** A sealed report as --follow prints it: id, milestone, title, then its evidence labels. */
+export function reportLine(r) {
+    const labels = r.evidence.map((e) => e.label).join(', ');
+    return `${r.id}\t${r.milestone}\t${oneLine(r.title, 100)}${labels ? `\t${labels}` : ''}`;
+}
+/** The board as text: Needs you first (oldest first), then Now, Next and Later in their order. */
+export function boardText(b) {
+    const parts = [];
+    if (b.needs_you.length)
+        parts.push(['Needs you', ...b.needs_you.map(needsLine)].join('\n'));
+    for (const bucket of BUCKETS) {
+        const tasks = b.tasks.filter((t) => t.bucket === bucket && !t.deleted_at && !t.cleared_at).sort((x, y) => x.position - y.position);
+        if (tasks.length)
+            parts.push([BUCKET_TITLES[bucket], ...tasks.map(taskLine)].join('\n'));
+    }
+    return parts.length ? `${parts.join('\n\n')}\n` : 'Nothing on the board yet: shard task add <words> adds a task.\n';
+}
+/** The approval policy on one line: the default, each project's own mode, the number of rules. */
+export function policyLine(p) {
+    const projects = Object.entries(p.projects).map(([id, mode]) => `; ${id}: ${mode}`).join('');
+    return `${p.default}${projects}${p.rules.length ? `; ${p.rules.length} rule${p.rules.length === 1 ? '' : 's'}` : ''}`;
+}
+/** One always-allow rule: id, tool, the pattern it allows, its project. */
+export function ruleLine(r) {
+    return `${r.id}\t${r.tool}\t${r.pattern || '(every use)'}\t${r.project_id ?? 'every project'}`;
+}
+/** `shard approvals`: the default mode, each project's own mode, then each rule. */
+export function policyText(p) {
+    return [`Default: ${p.default}`, ...Object.entries(p.projects).map(([id, mode]) => `Project ${id}: ${mode}`), ...p.rules.map(ruleLine)].join('\n') + '\n';
+}
+/**
+ * `shard board --follow`: the lines of each feed answer. A changed task is its board line plus its bucket (deleted,
+ * cleared once gone); a sealed report its report line; an item that started waiting on you its needs line, one that
+ * stopped `<id>\tresolved`; a policy change one line. After a reset the whole board is printed again.
+ */
+export class BoardFollower {
+    #waiting;
+    constructor(board) {
+        this.#waiting = new Set(board.needs_you.map((n) => n.id));
+    }
+    next(u) {
+        if (u.reset) {
+            this.#waiting = new Set(u.board.needs_you.map((n) => n.id));
+            return `\n${boardText(u.board)}`;
+        }
+        const lines = [];
+        if (u.needs_you) {
+            const now = new Set(u.needs_you.map((n) => n.id));
+            for (const n of u.needs_you)
+                if (!this.#waiting.has(n.id))
+                    lines.push(needsLine(n));
+            for (const id of this.#waiting)
+                if (!now.has(id))
+                    lines.push(`${id}\tresolved`);
+            this.#waiting = now;
+        }
+        for (const t of u.tasks)
+            lines.push(`${taskLine(t)}\t${t.deleted_at ? 'deleted' : t.cleared_at ? 'cleared' : t.bucket}`);
+        for (const r of u.reports)
+            lines.push(reportLine(r));
+        if (u.policy)
+            lines.push(`Approvals: ${policyLine(u.policy)}`);
+        return lines.length ? `${lines.join('\n')}\n` : '';
+    }
+}
+/** A feed answer as `board --follow --json` prints it: the API's fields (with `board` after a reset). */
+export function feedJson(u) {
+    const page = { ...u };
+    delete page.nextCursor;
+    delete page.held;
+    return page;
+}
+const evidenceText = (e) => {
+    const behind = e.detail ?? e.path;
+    return behind ? `${e.label} (${detailLine(behind, 60)})` : e.label;
+};
+/** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. */
+export function taskDetailText(d) {
+    const t = d.task;
+    const titled = Boolean(t.title?.trim());
+    const lines = [titled ? oneLine(t.title, 200) : oneLine(t.text.split('\n').find((l) => l.trim()) ?? t.text, 200)];
+    lines.push([`${t.state}${stateNote(t, 120)}`, t.bucket, `${t.project_id}${t.home ? ' (home)' : ''}`, ...(t.suggested ? ['suggested'] : []), ...(t.deleted_at ? ['deleted'] : t.cleared_at ? ['cleared'] : [])].join('\t'));
+    // Your words exactly, when the first line does not already show them whole.
+    if (titled || t.text.trim() !== lines[0])
+        lines.push('', t.text);
+    if (t.plan) {
+        lines.push('', `Plan: ${t.plan.summary}`);
+        for (const s of t.plan.steps)
+            lines.push(`  ${s.id}\t${s.state}\t${oneLine(s.text, 100)}${s.now?.trim() ? `\t(${oneLine(s.now, 80)})` : ''}${s.evidence.length ? `\t${s.evidence.join(', ')}` : ''}`);
+    }
+    if (t.conversations.length)
+        lines.push('', `Conversations: ${t.conversations.map((c) => `${c.id} (${c.role}${c.step_id ? ` ${c.step_id}` : ''})`).join(', ')}`);
+    if (d.reports.length) {
+        lines.push('', 'Reports');
+        for (const r of d.reports) {
+            lines.push(`${r.id}\t${r.milestone}\t${time(r.sealed_at)}\t${oneLine(r.title, 120)}`);
+            if (r.outcome.trim())
+                lines.push(`  ${oneLine(r.outcome, 200)}`);
+            if (r.options?.length)
+                lines.push(`  Options: ${r.options.join(' / ')}`);
+            if (r.evidence.length)
+                lines.push(`  Evidence: ${r.evidence.map(evidenceText).join('; ')}`);
+            if (r.media.length)
+                lines.push(`  Media: ${r.media.map((m) => `${m.name} (${m.path})`).join(', ')}`);
+            if (r.landed)
+                lines.push(`  Landed: ${r.landed.how} ${r.landed.ref}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** --now, --next or --later (one at most); undefined when none was given. */
+function bucketOf(values) {
+    const chosen = BUCKETS.filter((b) => values[b] === true);
+    if (chosen.length > 1)
+        throw new UsageError('Choose one of --now, --next or --later.');
+    return chosen[0];
+}
+/** --after <task-id> or --first (null: first); undefined when neither was given. */
+function orderOf(values) {
+    const after = str(values.after), first = values.first === true;
+    if (after !== undefined && first)
+        throw new UsageError('Choose --after <task-id> or --first.');
+    return first ? null : after;
+}
+// ---- needs you -------------------------------------------------------------------------------
+const KINDS = { perm: 'permission', cq: 'question', ask: 'question', cred: 'credential', land: 'land', prune: 'prune' };
+/** An item's kind from its id (perm_, cq_, ask_, cred_, land_, prune_); undefined for another id. */
+export function itemKind(id) {
+    return KINDS[id.slice(0, Math.max(0, id.indexOf('_')))];
+}
+/** The answer words: allow, always and deny (or the API's names), land, keep and discard. */
+const WORDS = { allow: 'allow_once', allow_once: 'allow_once', always: 'allow_always', allow_always: 'allow_always', deny: 'deny', land: 'land', keep: 'keep', discard: 'discard' };
+/** Whether the answer needs the item itself: the questions of a permission request, every task of a prune prompt. */
+export const answerNeedsItem = (id, a) => a.picks.length > 0 || (itemKind(id) === 'prune' && a.word?.toLowerCase() === 'keep');
+/**
+ * The API answer for item `id` from the command's words and options, checked before anything is sent: each kind takes
+ * its own (needs-you.ts). `item` is the waiting item when answerNeedsItem says it is needed; without it such an answer
+ * is only checked (its `answers` or `keep` come back empty).
+ */
+export function needsAnswer(id, a, item) {
+    const kind = item?.kind ?? itemKind(id);
+    const decision = a.word === undefined ? undefined : WORDS[a.word.toLowerCase().replace(/-/g, '_')];
+    const only = (allowed, message) => {
+        const given = ['text', 'picks', 'keep', 'everywhere'].filter((k) => (k === 'text' ? a.text !== undefined : k === 'everywhere' ? a.everywhere : a[k].length > 0));
+        if (given.some((k) => !allowed.includes(k)))
+            throw new UsageError(message);
+    };
+    switch (kind) {
+        case 'permission': {
+            const message = 'Choose allow, always or deny (an agent’s question takes --pick <option>).';
+            only(['picks', 'everywhere'], message);
+            if (a.picks.length) {
+                if (a.word !== undefined)
+                    throw new UsageError('Answer the question with --pick, or decline it with deny, not both.');
+                if (a.everywhere)
+                    throw new UsageError('--everywhere goes with always.');
+                if (!item)
+                    return { answers: {} };
+                return { answers: pickAnswers({ questions: (item.permission?.questions ?? []) }, a.picks) };
+            }
+            if (decision !== 'allow_once' && decision !== 'allow_always' && decision !== 'deny')
+                throw new UsageError(message);
+            if (a.everywhere && decision !== 'allow_always')
+                throw new UsageError('--everywhere goes with always.');
+            return decision === 'allow_always' ? { decision, scope: a.everywhere ? 'everywhere' : 'project' } : { decision };
+        }
+        case 'question': {
+            const message = 'Answer the question with --text <answer>.';
+            only(['text'], message);
+            if (a.word !== undefined || !a.text?.trim())
+                throw new UsageError(message);
+            return { text: a.text };
+        }
+        case 'credential':
+            only([], 'Provide the value through the credential request, sealed for its computer; deny declines it here.');
+            if (decision !== 'deny')
+                throw new UsageError('Provide the value through the credential request, sealed for its computer; deny declines it here.');
+            return { decision };
+        case 'land':
+            only([], 'Choose land, keep or discard.');
+            if (decision !== 'land' && decision !== 'keep' && decision !== 'discard')
+                throw new UsageError('Choose land, keep or discard.');
+            return { decision };
+        case 'prune': {
+            const message = 'Choose --keep <task-id> for each task to keep, keep for all of them, or discard to clear them.';
+            only(['keep'], message);
+            if (a.keep.length) {
+                if (a.word !== undefined)
+                    throw new UsageError(message);
+                return { keep: [...new Set(a.keep)] };
+            }
+            if (decision === 'discard')
+                return { keep: [] };
+            if (decision === 'keep')
+                return { keep: item?.prune ? [...item.prune.task_ids] : [] };
+            throw new UsageError(message);
+        }
+        default: {
+            // An id of a kind this shard does not know yet: what was given goes to the API, which says what it takes.
+            const answer = {};
+            if (decision)
+                answer.decision = decision;
+            if (a.text !== undefined)
+                answer.text = a.text;
+            if (a.keep.length)
+                answer.keep = [...a.keep];
+            if (a.everywhere)
+                answer.scope = 'everywhere';
+            return answer;
+        }
+    }
+}
+const ANSWERED = { allow_once: 'Allowed once', allow_always: 'Always allowed', deny: 'Denied', land: 'Landing', keep: 'Kept', discard: 'Discarded' };
+/** What an answer did, in one line. */
+export function answeredText(r, a) {
+    const item = r.item;
+    if (a.answers)
+        return `Answered: ${Object.values(a.answers).map((v) => (Array.isArray(v) ? v.join(', ') : v)).join('; ')}\n`;
+    if (item.kind === 'prune' && a.keep) {
+        const all = item.prune?.task_ids.length ?? a.keep.length;
+        return a.keep.length === all ? `Kept all ${all} Later tasks.\n` : `Kept ${a.keep.length} of ${all} Later tasks; the rest are cleared.\n`;
+    }
+    if (item.kind === 'question')
+        return `Answered: ${oneLine(item.ask, 100)}\n`;
+    const what = item.kind === 'land' ? item.land?.branch ?? oneLine(item.ask, 100) : oneLine(item.ask, 100).replace(/\?$/, '');
+    return `${ANSWERED[a.decision ?? ''] ?? 'Answered'}: ${what}${r.rule_id ? ` (rule ${r.rule_id})` : ''}\n`;
+}
+// ---- handlers --------------------------------------------------------------------------------
+const projectScope = (values) => (str(values.project) !== undefined ? { projectId: str(values.project) } : {});
+export const BOARD_HANDLERS = {
+    // The board, or with --follow the board and then each change until Ctrl-C (the SDK's watch over the held feed,
+    // from the board's own cursor: nothing between the read and the first wait is missed).
+    async board(ctx, values) {
+        const cloud = boardClient(ctx), scope = projectScope(values);
+        const board = await cloud.board.get({ ...scope, signal: ctx.signal });
+        if (values.follow !== true) {
+            out(ctx, boardText(board), board);
+            return 0;
+        }
+        ctx.io.stdout.write(ctx.json ? `${JSON.stringify(board)}\n` : boardText(board));
+        progress(ctx, 'Following the board. Ctrl-C stops.');
+        const follower = new BoardFollower(board);
+        for await (const u of cloud.board.watch({ ...scope, cursor: board.cursor, signal: ctx.signal })) {
+            ctx.io.stdout.write(ctx.json ? `${JSON.stringify(feedJson(u))}\n` : follower.next(u));
+        }
+        return 0;
+    },
+    async 'task add'(ctx, values, words) {
+        const text = words.join(' ');
+        if (!text.trim())
+            throw new UsageError('missing <words...> for "shard task add"');
+        if (values.next === true && values.later === true)
+            throw new UsageError('Choose --next or --later.');
+        const bucket = values.later === true ? 'later' : values.next === true ? 'next' : undefined;
+        const after = orderOf(values);
+        const task = await boardClient(ctx).tasks.create({ text, ...projectScope(values), ...(values.home === true ? { home: true } : {}), ...(bucket ? { bucket } : {}), ...(after !== undefined ? { after } : {}) }, { signal: ctx.signal });
+        out(ctx, `${task.id}\t${task.bucket}\t${task.state}\n`, { task });
+        return 0;
+    },
+    async 'task show'(ctx, _values, [id]) {
+        const detail = await boardClient(ctx).tasks.get(id, { signal: ctx.signal });
+        out(ctx, taskDetailText(detail), detail);
+        return 0;
+    },
+    async 'task edit'(ctx, values, [id]) {
+        const p = {};
+        const text = str(values.text), title = str(values.title);
+        if (text !== undefined) {
+            if (!text.trim())
+                throw new UsageError('--text needs words.');
+            p.text = text;
+        }
+        if (title !== undefined)
+            p.title = title.trim() ? title : null;
+        const bucket = bucketOf(values), after = orderOf(values);
+        if (bucket)
+            p.bucket = bucket;
+        if (after !== undefined)
+            p.after = after;
+        if (values.keep === true)
+            p.suggested = false;
+        if (typeof values.clear === 'boolean')
+            p.cleared = values.clear;
+        if (Object.keys(p).length === 0)
+            throw new UsageError('Nothing to change: give --text, --title, --now, --next, --later, --after, --first, --keep or --clear.');
+        const task = await boardClient(ctx).tasks.update(id, p, { signal: ctx.signal });
+        out(ctx, `${taskLine(task)}\n`, { task });
+        return 0;
+    },
+    async 'task rm'(ctx, _values, [id]) {
+        const task = await boardClient(ctx).tasks.delete(id, { signal: ctx.signal });
+        out(ctx, `Deleted: ${taskLabel(task)}\n`, { task });
+        return 0;
+    },
+    async 'task steer'(ctx, _values, [id, ...words]) {
+        const text = words.join(' ');
+        if (!text.trim())
+            throw new UsageError('missing <words...> for "shard task steer"');
+        const task = await boardClient(ctx).tasks.steer(id, text, { signal: ctx.signal });
+        out(ctx, `Steered: ${taskLabel(task)}\n`, { task });
+        return 0;
+    },
+    async 'task land'(ctx, values, [id]) {
+        const o = await landTask(landDeps(ctx), id, { path: str(values.path) });
+        out(ctx, landedText(o), o);
+        return 0;
+    },
+    async 'task clear-done'(ctx, values) {
+        const cleared = await boardClient(ctx).tasks.clearDone(projectScope(values), { signal: ctx.signal });
+        out(ctx, cleared.length ? `Cleared ${cleared.length} finished task${cleared.length === 1 ? '' : 's'}.\n` : 'No finished tasks to clear.\n', { cleared });
+        return 0;
+    },
+    async 'needs-you'(ctx, values) {
+        const data = await boardClient(ctx).needsYou.list({ ...projectScope(values), signal: ctx.signal });
+        out(ctx, data.length ? `${data.map(needsLine).join('\n')}\n` : 'Nothing waits on you.\n', { data });
+        return 0;
+    },
+    async 'needs-you answer'(ctx, values, [id, word]) {
+        const input = { word, text: str(values.text), picks: strs(values.pick), keep: strs(values.keep), everywhere: values.everywhere === true };
+        const cloud = boardClient(ctx);
+        // Land merges here (shard task land) and records itself after; the board only takes keep and discard.
+        if (itemKind(id) === 'land' && word?.toLowerCase() === 'land') {
+            const o = await landTask(landDeps(ctx), id.replace(/^land_/, ''), {});
+            out(ctx, landedText(o), o);
+            return 0;
+        }
+        // Checked first, so a wrong combination is a usage error before any request.
+        let answer = needsAnswer(id, input);
+        if (answerNeedsItem(id, input)) {
+            const item = (await cloud.needsYou.list({ signal: ctx.signal })).find((n) => n.id === id);
+            if (!item)
+                throw new NotFoundError('Nothing waits on you there any more.', 'shard needs-you lists what does', { reason: 'needs_you_not_found' });
+            answer = needsAnswer(id, input, item);
+        }
+        const r = await cloud.needsYou.answer(id, answer, { signal: ctx.signal });
+        out(ctx, answeredText(r, answer), r);
+        return 0;
+    },
+    async approvals(ctx) {
+        const policy = await boardClient(ctx).approvals.getPolicy({ signal: ctx.signal });
+        out(ctx, policyText(policy), policy);
+        return 0;
+    },
+    async 'approvals set'(ctx, values, [word]) {
+        const w = word.toLowerCase();
+        if (w !== 'default' && !MODES.includes(w))
+            throw new UsageError('Choose ask, routine or trusted (default puts the project back on the default mode).');
+        const mode = w === 'default' ? null : w, project = str(values.project);
+        if (values.default === true && project !== undefined)
+            throw new UsageError('Choose --project <id> or --default.');
+        if (values.default === true && mode === null)
+            throw new UsageError('--default takes ask, routine or trusted.');
+        const cloud = boardClient(ctx);
+        const params = values.default === true ? { default: mode } : { projects: { [project ?? (await principal(ctx)).project_id]: mode } };
+        const policy = await cloud.approvals.setPolicy(params, { signal: ctx.signal });
+        out(ctx, policyText(policy), policy);
+        return 0;
+    },
+    async 'approvals allow'(ctx, values, [tool, ...pattern]) {
+        const project = str(values.project), everywhere = values.everywhere === true;
+        if (project !== undefined && everywhere)
+            throw new UsageError('Choose --project <id> or --everywhere.');
+        if (!tool.trim())
+            throw new UsageError('Name the tool, such as Bash, WebFetch or Edit.');
+        const rule = await boardClient(ctx).approvals.addRule({ tool: tool, pattern: pattern.join(' '), ...(everywhere ? { projectId: null } : project !== undefined ? { projectId: project } : {}) }, { signal: ctx.signal });
+        out(ctx, `${ruleLine(rule)}\n`, rule);
+        return 0;
+    },
+    async 'approvals remove'(ctx, _values, [id]) {
+        const policy = await boardClient(ctx).approvals.removeRule(id, { signal: ctx.signal });
+        out(ctx, `Removed ${id}.\n`, policy);
+        return 0;
+    },
+};

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) {