@shardflux/cli 0.14.5 → 0.15.0

package/dist/onboarding.d.ts

@@ -0,0 +1,258 @@
+import type { Ctx } from './commands.js';
+import type { Values } from './args.js';
+import type { CodexConnectorView, CodexHealth } from './codex-cloud.js';
+/**
+ * The first-run demo's task: it shows the agent's own computer at work. The user copies it and pastes it into the
+ * launcher themselves; Daylight's own CLAUDE.md and AGENTS.md say how to run it and test it in the desktop browser.
+ */
+export declare const DEMO_PROMPT = "Start Daylight and test it in the browser, then tell me what works.";
+export type AgentApp = 'claude' | 'codex';
+/**
+ * Where Claude Code and Codex install their commands in a home folder. Apps opened from the Finder (the menu bar app,
+ * and this CLI run by it) get a minimal PATH; the menu bar app adds Homebrew's and /usr/local/bin, and these cover the
+ * rest (Claude Code's installer uses ~/.local/bin).
+ */
+export declare function installDirs(home: string): string[];
+/** Claude Code or Codex is on this Mac: its home folder (~/.claude, ~/.codex) or its command on PATH or in an install folder. */
+export declare function foundApps(env: NodeJS.ProcessEnv): Promise<AgentApp[]>;
+/** --apps claude,codex (repeatable or comma separated); unknown names are refused. */
+export declare function parseApps(value: unknown): AgentApp[] | undefined;
+type CredentialRow = {
+    app: string;
+    status?: string;
+    scope?: string;
+    access?: {
+        verdict: 'usable' | 'refused' | 'unknown';
+        checked_at: string;
+    };
+};
+type Action = {
+    title: string;
+    command?: string[];
+    retry?: boolean;
+};
+export interface Connection {
+    id: 'account' | AgentApp | 't3';
+    /**
+     * verified: checked live just now. action: the person does `action`. pending: it is getting there on its own.
+     * unknown: ask again. info: nothing to do here yet (T3 Code: after a project is picked, or its provider's own Sign in).
+     */
+    state: 'verified' | 'action' | 'pending' | 'unknown' | 'info';
+    /** For scripts: the command that connects it later (T3 Code over SSH, once there is a project). */
+    next?: string[];
+    fact: string;
+    action?: Action;
+    picked?: boolean;
+    found?: boolean;
+    /** T3 Code only: optional (never needed to continue), its app (for the icon) and how it connects. */
+    optional?: boolean;
+    app_path?: string;
+    mode?: 'provider' | 'ssh';
+}
+/**
+ * T3 Code, when it is installed: an ACP-capable build (0.0.46+, nightly) has Shardflux as a provider, which every
+ * `shard` run writes into T3's settings, so it is connected with nothing to sign in; stable 0.0.45 connects a project
+ * over SSH (`shard agents new --in t3`), and says which environment to add. Null when T3 Code is not installed.
+ */
+export declare function t3Connection(ctx: Ctx, signedIn: boolean, appDirs?: string[], platform?: NodeJS.Platform): Promise<Connection | null>;
+/** Claude: the account login is ready and Claude itself accepts it right now. */
+export declare function claudeConnection(row: CredentialRow | undefined): Omit<Connection, 'id' | 'picked' | 'found'>;
+/** Codex: this Mac's Codex login is copied and the account's Codex remote device (one executor) is connected. */
+export declare function codexConnection(local: boolean, synced: boolean, connector: CodexConnectorView | null, health: CodexHealth): Omit<Connection, 'id' | 'picked' | 'found'>;
+/**
+ * The onboarding report, for an agent setting itself up from chat and for the menu bar app. It verifies every
+ * connection live: the Shardflux account, Claude (Claude itself accepts the login) and Codex (the login is copied and
+ * the account's Codex remote device is connected), for the apps picked (--apps, else saved, else found on this Mac).
+ * With --connect it also does what needs no sign-in: copies the Codex login and enables the Codex remote device.
+ */
+export declare function onboardingReport(ctx: Ctx, values: Values): Promise<{
+    version: number;
+    api_url: string;
+    apps: AgentApp[];
+    found_apps: AgentApp[];
+    connections: Connection[];
+    ready: boolean;
+    account_error: string | null;
+    demo: {
+        prompt: string;
+        project: string;
+        prepare: string[];
+    };
+    activity: {
+        state: "running" | "failed" | "suspended" | "deleted" | "creating" | "starting" | "suspending" | "resuming" | "forking" | "stopping" | "deleting";
+        workspace: {
+            id: string;
+            key: string;
+        };
+        conversation: {
+            id: string;
+            state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+            summary: string;
+        } | null;
+        commands: never[];
+        processes: never[];
+        ports: never[];
+        installs: never[];
+        screen: null;
+        browser: null;
+        changes: {
+            files: number;
+            commits: number;
+        };
+    } | {
+        changes: {
+            files: number;
+            commits: number;
+        };
+        observed_at: string;
+        screen: {
+            width: number;
+            height: number;
+        } | null;
+        browser: BrowserWindow | null;
+        state: string;
+        workspace: {
+            id: string;
+            key: string;
+        };
+        conversation: {
+            id: string;
+            state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+            summary: string;
+        } | null;
+        commands: string[];
+        processes: {
+            command: string;
+            started_at: string | null;
+        }[];
+        ports: number[];
+        installs: {
+            packages: string[];
+            sudo: boolean;
+        }[];
+    } | null;
+    steps: ({
+        id: string;
+        title: string;
+        status: string;
+        command: string[];
+        action?: undefined;
+    } | {
+        id: string;
+        title: string;
+        status: string;
+        command?: undefined;
+        action?: undefined;
+    } | {
+        id: string;
+        title: string;
+        status: string;
+        action: string;
+        command?: undefined;
+    })[];
+}>;
+/** The report as text: one line per connection, then what to do next. */
+export declare function onboardingText(report: Awaited<ReturnType<typeof onboardingReport>>): string;
+interface ProcessRow {
+    pid: number;
+    comm: string;
+    cmdline?: string[];
+    started_at?: string | null;
+}
+/** Node names its main thread "MainThread" and npm retitles itself "npm run dev": the program is the first argument. */
+export declare function activeCommands(processes: ProcessRow[]): string[];
+/** Commands and listening ports of a running VM. Never wakes a parked computer. */
+export declare function liveActivity(ctx: Ctx, ref: string): Promise<{
+    state: "running" | "failed" | "suspended" | "deleted" | "creating" | "starting" | "suspending" | "resuming" | "forking" | "stopping" | "deleting";
+    workspace: {
+        id: string;
+        key: string;
+    };
+    conversation: {
+        id: string;
+        state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+        summary: string;
+    } | null;
+    commands: never[];
+    processes: never[];
+    ports: never[];
+    installs: never[];
+    screen: null;
+    browser: null;
+    changes: {
+        files: number;
+        commits: number;
+    };
+} | {
+    changes: {
+        files: number;
+        commits: number;
+    };
+    observed_at: string;
+    screen: {
+        width: number;
+        height: number;
+    } | null;
+    browser: BrowserWindow | null;
+    state: string;
+    workspace: {
+        id: string;
+        key: string;
+    };
+    conversation: {
+        id: string;
+        state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+        summary: string;
+    } | null;
+    commands: string[];
+    processes: {
+        command: string;
+        started_at: string | null;
+    }[];
+    ports: number[];
+    installs: {
+        packages: string[];
+        sudo: boolean;
+    }[];
+}>;
+/** The ranked commands with when each started: a dev server that restarts after a save starts again. */
+export declare function activeProcesses(processes: ProcessRow[]): Array<{
+    command: string;
+    started_at: string | null;
+}>;
+/**
+ * What was installed with sudo since the workspace was created, from apt's own history: the packages each
+ * `apt-get install` asked for (not their automatic dependencies). Short installs finish between two process samples;
+ * the history keeps them. Entries without Requested-By ran as root, like the image build.
+ */
+export declare function aptInstalls(history: string, since?: string): Array<{
+    packages: string[];
+    sudo: boolean;
+}>;
+export declare function gitChanges(output: string): {
+    files: number;
+    commits: number;
+};
+/**
+ * The desktop's size and its largest visible browser window, so a live view can show the page the agent is testing
+ * rather than the whole screen with its panel and clock. Null fields when the desktop or the browser is not open.
+ */
+type BrowserWindow = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    title: string;
+};
+export declare function desktopWindows(output: string): {
+    screen: {
+        width: number;
+        height: number;
+    } | null;
+    browser: BrowserWindow | null;
+};
+/** "/usr/local/bin/node server.mjs" reads as "node server.mjs"; long arguments are cut. */
+export declare function commandLine(argv: string[]): string;
+/** Listening TCP ports from `ss -ltnp` or /proc/net/tcp{,6}, without the harness's or the desktop viewer's own ports. */
+export declare function listeningPorts(output: string): number[];
+export {};

package/dist/onboarding.js

@@ -0,0 +1,371 @@
+import { readFile, stat } from 'node:fs/promises';
+import { delimiter, join, resolve, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { resolveWorkspace } from "./commands.js";
+import { readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";
+import { getConversation } from "./conversations.js";
+import { codexHealth, readCodexConnector, restartCodexConnector } from "./codex-cloud.js";
+import { applicationDirs, t3Apps } from "./agent-targets.js";
+import { configureT3Provider, t3BundleSupportsAcp } from "./t3-provider.js";
+/**
+ * The first-run demo's task: it shows the agent's own computer at work. The user copies it and pastes it into the
+ * launcher themselves; Daylight's own CLAUDE.md and AGENTS.md say how to run it and test it in the desktop browser.
+ */
+export const DEMO_PROMPT = 'Start Daylight and test it in the browser, then tell me what works.';
+const APPS = ['claude', 'codex'];
+async function jsonFile(path) {
+    try {
+        const data = await readFile(path, 'utf8');
+        return JSON.parse(data);
+    }
+    catch {
+        return undefined;
+    }
+}
+const exists = (path) => stat(path).then(() => true, () => false);
+/**
+ * Where Claude Code and Codex install their commands in a home folder. Apps opened from the Finder (the menu bar app,
+ * and this CLI run by it) get a minimal PATH; the menu bar app adds Homebrew's and /usr/local/bin, and these cover the
+ * rest (Claude Code's installer uses ~/.local/bin).
+ */
+export function installDirs(home) {
+    return [join(home, '.local', 'bin'), join(home, '.claude', 'local'), join(home, '.npm-global', 'bin'), join(home, '.bun', 'bin'),
+        join(home, '.volta', 'bin'), join(home, 'Library', 'pnpm')];
+}
+/** Claude Code or Codex is on this Mac: its home folder (~/.claude, ~/.codex) or its command on PATH or in an install folder. */
+export async function foundApps(env) {
+    const home = env.HOME ?? homedir();
+    const onPath = async (name) => {
+        for (const dir of [...(env.PATH ?? '').split(delimiter).filter(Boolean), ...installDirs(home)])
+            if (await exists(join(dir, name)))
+                return true;
+        return false;
+    };
+    const found = [];
+    for (const app of APPS)
+        if (await exists(join(home, `.${app}`)) || await onPath(app))
+            found.push(app);
+    return found;
+}
+/** --apps claude,codex (repeatable or comma separated); unknown names are refused. */
+export function parseApps(value) {
+    if (value === undefined)
+        return undefined;
+    const words = (Array.isArray(value) ? value : [value]).flatMap(v => String(v).split(',')).map(v => v.trim()).filter(Boolean);
+    for (const word of words)
+        if (!APPS.includes(word))
+            throw new Error('--apps takes claude, codex or both');
+    return APPS.filter(app => words.includes(app));
+}
+/**
+ * T3 Code, when it is installed: an ACP-capable build (0.0.46+, nightly) has Shardflux as a provider, which every
+ * `shard` run writes into T3's settings, so it is connected with nothing to sign in; stable 0.0.45 connects a project
+ * over SSH (`shard agents new --in t3`), and says which environment to add. Null when T3 Code is not installed.
+ */
+export async function t3Connection(ctx, signedIn, appDirs = applicationDirs(ctx.io.env), platform = process.platform) {
+    const app = t3Apps(appDirs, platform)[0];
+    if (!app)
+        return null;
+    const base = { id: 't3', optional: true, found: true, app_path: app.path };
+    if (t3BundleSupportsAcp(app.path)) {
+        try {
+            await configureT3Provider(ctx.io.env, ctx.store.dir, false, ctx.signal);
+            // The provider works once there is an API key; without an account its own Sign in (shard acp --login) makes one.
+            if (!signedIn)
+                return { ...base, mode: 'provider', state: 'info', fact: 'In T3 Code, the Shardflux provider’s Sign in finishes it.' };
+            return { ...base, mode: 'provider', state: 'verified', fact: 'Shardflux added as a provider. Pick a Shardflux model in a new thread.' };
+        }
+        catch (error) {
+            return { ...base, mode: 'provider', state: 'action', fact: error instanceof Error ? error.message : 'T3 Code’s settings could not be updated.', action: { title: 'Check again' } };
+        }
+    }
+    // Stable T3: an SSH environment per project; the newest one this API set up is the one to add.
+    const manifest = await jsonFile(join(ctx.store.dir, 'targets.json'));
+    const entries = Array.isArray(manifest?.entries) ? manifest.entries : [];
+    const host = entries.filter(e => e.api_url === ctx.apiUrl && Array.isArray(e.targets) && e.targets.includes('t3') && typeof e.host === 'string').map(e => e.host).at(-1);
+    if (host)
+        return { ...base, mode: 'ssh', state: 'verified', fact: `In T3 Code: Add environment → SSH → ${host}` };
+    // An SSH environment is per project (shardflux-<project>-main): it is set up once a project is picked.
+    return { ...base, mode: 'ssh', state: 'info', fact: 'Available after you pick a project.', next: shard(['agents', 'new', '--in', 't3', '--path', '<project>']) };
+}
+const shard = (words) => ['shard', ...words];
+/** Claude: the account login is ready and Claude itself accepts it right now. */
+export function claudeConnection(row) {
+    const signIn = { title: 'Sign in to Claude', command: shard(['agents', 'credentials', 'login', 'claude']) };
+    if (!row || row.status !== 'ready')
+        return { state: 'action', fact: 'Sign in once; every conversation uses it.', action: signIn };
+    // Only a refusal blocks. Usable, unknown (Claude did not answer) and an API without the live check all accept the
+    // stored ready login: a check that learned nothing is not a reason to stop someone.
+    if (row.access?.verdict === 'refused')
+        return { state: 'action', fact: 'Claude no longer accepts this sign-in.', action: { ...signIn, title: 'Sign in to Claude again' } };
+    return { state: 'verified', fact: 'Signed in. Works in every conversation, on web and phone.' };
+}
+/** Codex: this Mac's Codex login is copied and the account's Codex remote device (one executor) is connected. */
+export function codexConnection(local, synced, connector, health) {
+    const enable = { title: 'Connect Codex', command: shard(['agents', 'codex', 'enable']) };
+    if (!synced) {
+        return local ? { state: 'action', fact: 'Available on web and phone once connected.', action: enable }
+            : { state: 'action', fact: 'Sign in to Codex on this Mac first.', action: { title: 'Sign in to Codex', command: ['codex', 'login'] } };
+    }
+    const retry = { title: 'Retry', retry: true, command: shard(['setup', '--inspect', '--apps', 'codex', '--connect', '--retry-codex']) };
+    switch (health) {
+        case 'ready': return { state: 'verified', fact: 'Available on web and phone.' };
+        case 'missing':
+        case 'disabled':
+            return { state: 'action', fact: 'Available on web and phone once connected.', action: enable };
+        case 'starting': return { state: 'pending', fact: 'Connecting your Codex remote device…' };
+        case 'failed': return { state: 'action', fact: 'Codex’s remote device didn’t start.', action: retry };
+        case 'stuck': return { state: 'action', fact: 'Codex’s remote device is taking too long to start.', action: retry };
+        case 'attention': return { state: 'action', fact: connector?.last_error ? `Codex needs attention: ${connector.last_error}` : 'Codex needs attention.', action: retry };
+    }
+}
+/**
+ * The onboarding report, for an agent setting itself up from chat and for the menu bar app. It verifies every
+ * connection live: the Shardflux account, Claude (Claude itself accepts the login) and Codex (the login is copied and
+ * the account's Codex remote device is connected), for the apps picked (--apps, else saved, else found on this Mac).
+ * With --connect it also does what needs no sign-in: copies the Codex login and enables the Codex remote device.
+ */
+export async function onboardingReport(ctx, values) {
+    const saved = await jsonFile(resolve(ctx.store.dir, 'onboarding.json'));
+    const state = saved?.api_url === ctx.apiUrl ? saved : undefined;
+    const found = await foundApps(ctx.io.env);
+    // An empty saved pick means nothing was chosen yet: what is found on this Mac is pre-ticked.
+    const savedApps = Array.isArray(state?.apps) && state.apps.length ? parseApps(state.apps.filter(v => typeof v === 'string')) : undefined;
+    const apps = parseApps(values.apps) ?? savedApps ?? found;
+    const connect = values.connect === true;
+    let connected = false;
+    let accountError = null;
+    let credentials = [];
+    let connector = null;
+    let health = 'missing';
+    const home = ctx.io.env.HOME ?? ctx.io.env.USERPROFILE;
+    const localCodex = home ? (await readAgentCredentials({ home, redact: value => ctx.addSecret(value) })).some(v => v.app === 'codex') : false;
+    try {
+        ctx.apiKey();
+        const principal = await ctx.cloud().me();
+        connected = principal.type === 'api_key';
+    }
+    catch (error) {
+        accountError = error instanceof Error ? error.message : 'Sign in to Shardflux, then check again.';
+    }
+    // An API from before the live Claude check refuses check_access (422): read the stored status instead.
+    const listCredentials = async () => {
+        if (!apps.includes('claude'))
+            return await ctx.cloud().agentCredentials.list();
+        try {
+            return await ctx.cloud().agentCredentials.list({ checkAccess: true });
+        }
+        catch (error) {
+            if (error.status !== 422)
+                throw error;
+            return await ctx.cloud().agentCredentials.list();
+        }
+    };
+    // A check that fails says so on its own row; it never fails the report (or `shard setup`, which includes it).
+    const failure = (error) => ({ state: 'unknown', fact: `Couldn’t check: ${error instanceof Error ? error.message : String(error)}`, action: { title: 'Check again' } });
+    let credentialError, codexError;
+    if (connected) {
+        try {
+            credentials = await listCredentials();
+        }
+        catch (error) {
+            credentialError = error;
+        }
+        if (apps.includes('codex') && credentialError === undefined) {
+            try {
+                if (connect && localCodex && !credentials.some(row => row.app === 'codex') && home) {
+                    await syncAgentCredentials(ctx.cloud(), { home, redact: value => ctx.addSecret(value) });
+                    credentials = await listCredentials();
+                }
+                let read = await readCodexConnector(ctx);
+                health = codexHealth(read.connector, read.workspaceState);
+                const synced = credentials.some(row => row.app === 'codex');
+                // One executor per account, enabled as `shard setup` does when this Mac is signed in to Codex. --retry-codex starts
+                // a failed or stuck one again, once.
+                if (connect && synced && (health === 'missing' || health === 'disabled')) {
+                    read = { connector: await ctx.cloud().codex.enable({ signal: ctx.signal }), workspaceState: null };
+                    health = codexHealth(read.connector, null);
+                }
+                else if (connect && synced && values['retry-codex'] === true && (health === 'failed' || health === 'stuck' || health === 'attention')) {
+                    read = { connector: await restartCodexConnector(ctx), workspaceState: null };
+                    health = codexHealth(read.connector, null);
+                }
+                connector = read.connector;
+            }
+            catch (error) {
+                codexError = error;
+            }
+        }
+    }
+    const account = connected ? { id: 'account', state: 'verified', fact: 'Signed in.' }
+        : { id: 'account', state: 'action', fact: 'Sign in to Shardflux to continue.', action: { title: 'Sign in', command: shard(['signup']) } };
+    const signIn = { state: 'action', fact: 'Sign in to Shardflux first.' };
+    const claude = { id: 'claude', picked: apps.includes('claude'), found: found.includes('claude'),
+        ...(!connected ? signIn : credentialError !== undefined ? failure(credentialError) : claudeConnection(credentials.find(row => row.app === 'claude'))) };
+    const codex = { id: 'codex', picked: apps.includes('codex'), found: found.includes('codex'),
+        ...(!connected ? signIn : (credentialError ?? codexError) !== undefined ? failure(credentialError ?? codexError)
+            : codexConnection(localCodex, credentials.some(row => row.app === 'codex'), connector, health)) };
+    const t3 = await t3Connection(ctx, connected);
+    const connections = [account, claude, codex, ...(t3 ? [t3] : [])];
+    // Ready: signed in and at least one agent app connected; the other can be connected later (Settings, or this again).
+    const ready = account.state === 'verified' && [claude, codex].some(c => c.state === 'verified');
+    const done = (value) => value === true || (typeof value === 'string' && value.length > 0);
+    return {
+        version: 3, api_url: ctx.apiUrl, apps, found_apps: found, connections, ready, account_error: accountError,
+        demo: { prompt: DEMO_PROMPT, project: 'Daylight (sample)', prepare: shard(['setup', '--prepare-sample', '--json']) },
+        activity: values.activity === true && typeof values.workspace === 'string' ? await liveActivity(ctx, values.workspace) : null,
+        steps: [
+            { id: 'account', title: 'Sign in to Shardflux', status: connected ? 'complete' : 'available', command: shard(['signup']) },
+            { id: 'connect', title: 'Connect Claude, Codex or both', status: ready ? 'complete' : 'available' },
+            { id: 'demo', title: 'Try it once: your agent’s own computer', status: done(state?.demo_finished) ? 'complete' : 'available',
+                action: 'Copy the task, press ⌥⇧Space, paste it, pick Daylight (sample) and start it. The agent installs what it needs, starts it and tests it in its own browser.' },
+            { id: 'own', title: 'Your own project', status: done(state?.own_key) ? 'complete' : 'available',
+                action: 'Press ⌥⇧Space, pick your project and describe what you want.' },
+        ],
+    };
+}
+/** The report as text: one line per connection, then what to do next. */
+export function onboardingText(report) {
+    const names = { account: 'Shardflux', claude: 'Claude', codex: 'Codex', t3: 'T3 Code' };
+    const mark = { verified: '✓', action: '!', pending: '…', unknown: '?', info: '·' };
+    const lines = report.connections.filter(c => c.id === 'account' || c.picked || c.id === 't3').map(c => `${mark[c.state]} ${names[c.id]}: ${c.fact}${c.action?.command ? ` (${c.action.command.join(' ')})` : ''}`);
+    return `${lines.join('\n')}\n${report.ready ? `Ready. Try it once: ${report.demo.prompt}` : 'Not ready yet: finish the steps above, then run this again.'}\n`;
+}
+/** What a person recognises, most telling first: installs, then how the app is run, then what it runs. */
+const RANKS = [/^(sudo|apt|apt-get|dpkg)$/, /^(npm|npx|pnpm|yarn|bun)$/, /^(node|python[0-9.]*|uv|vite|next|deno|docker|cargo|go|make)$/, /^(pip[0-9.]*|inotifywait)$/];
+const AGENT_INTERNALS = /\/opt\/(codex|claude)\/|sf-agent|\.claude\/|shardflux/;
+/** Node names its main thread "MainThread" and npm retitles itself "npm run dev": the program is the first argument. */
+export function activeCommands(processes) {
+    const rows = processes.map(p => {
+        const argv = p.cmdline?.length ? p.cmdline : [p.comm];
+        const program = basename(argv[0].split(' ')[0]);
+        return { argv, rank: RANKS.findIndex(rank => rank.test(program)), started: Date.parse(p.started_at ?? '') || p.pid };
+    }).filter(row => row.rank >= 0 && !AGENT_INTERNALS.test(row.argv.join(' ')));
+    rows.sort((a, b) => a.rank - b.rank || b.started - a.started);
+    return [...new Set(rows.map(row => commandLine(row.argv)))].slice(0, 3);
+}
+/** Commands and listening ports of a running VM. Never wakes a parked computer. */
+export async function liveActivity(ctx, ref) {
+    // A Codex Cloud conversation is named by its id (conv_…); its VM is the conversation's workspace.
+    let conversation = ref.startsWith('conv_') ? await getConversation(ctx, ref) : undefined;
+    const workspace = await resolveWorkspace(ctx, conversation?.workspace_id ?? ref);
+    if (!conversation && workspace.data.labels?.shard_conversation) {
+        conversation = await getConversation(ctx, workspace.data.labels.shard_conversation).catch(() => undefined);
+    }
+    const turn = conversation ? { id: conversation.id, state: conversation.state, summary: conversation.summary } : null;
+    const identity = { id: workspace.id, key: workspace.key };
+    if (workspace.data.deleted_at || workspace.data.observed_state !== 'running') {
+        return { state: workspace.data.observed_state, workspace: identity, conversation: turn, commands: [], processes: [], ports: [], installs: [], screen: null, browser: null, changes: { files: 0, commits: 0 } };
+    }
+    const cell = workspace.cell({ wake: null });
+    try {
+        const since = workspace.data.created_at ?? '';
+        const [processes, sockets, apt, windows, git] = await Promise.all([
+            cell.processes.list(),
+            cell.exec.run(['sh', '-c', LISTENERS], { timeoutMs: 3000, maxOutputBytes: 64 * 1024 }).catch(() => null),
+            cell.exec.run(['tail', '-c', '32768', '/var/log/apt/history.log'], { timeoutMs: 3000, maxOutputBytes: 40 * 1024 }).catch(() => null),
+            cell.exec.run(['sh', '-c', DESKTOP_WINDOWS], { timeoutMs: 3000, maxOutputBytes: 16 * 1024 }).catch(() => null),
+            cell.exec.run(['sh', '-c', GIT_CHANGES, 'git-changes', since], { timeoutMs: 5000, maxOutputBytes: 16 * 1024 }).catch(() => null),
+        ]);
+        return { state: 'running', workspace: identity, conversation: turn, commands: activeCommands(processes.data), processes: activeProcesses(processes.data),
+            ports: listeningPorts(sockets?.stdout ?? ''), installs: aptInstalls(apt?.stdout ?? '', workspace.data.created_at),
+            ...desktopWindows(windows?.stdout ?? ''), changes: gitChanges(git?.stdout ?? ''), observed_at: new Date().toISOString() };
+    }
+    finally {
+        cell.close();
+    }
+}
+/** The ranked commands with when each started: a dev server that restarts after a save starts again. */
+export function activeProcesses(processes) {
+    const out = [];
+    for (const command of activeCommands(processes)) {
+        const starts = processes.filter(p => commandLine(p.cmdline?.length ? p.cmdline : [p.comm]) === command).map(p => p.started_at ?? null).filter((v) => !!v).sort();
+        out.push({ command, started_at: starts.at(-1) ?? null });
+    }
+    return out;
+}
+/**
+ * What was installed with sudo since the workspace was created, from apt's own history: the packages each
+ * `apt-get install` asked for (not their automatic dependencies). Short installs finish between two process samples;
+ * the history keeps them. Entries without Requested-By ran as root, like the image build.
+ */
+export function aptInstalls(history, since) {
+    const from = since ? Date.parse(since) : NaN;
+    const out = [];
+    for (const entry of history.split(/\n\s*\n/)) {
+        const field = (name) => entry.match(new RegExp(`^${name}: (.*)$`, 'm'))?.[1]?.trim();
+        const command = field('Commandline'), started = field('Start-Date'), by = field('Requested-By');
+        if (!command || !by || !/\b(apt-get|apt)\s+install\b/.test(command))
+            continue;
+        const when = started ? Date.parse(started.replace(/\s+/, 'T') + 'Z') : NaN;
+        if (Number.isFinite(from) && (!Number.isFinite(when) || when < from - 60_000))
+            continue;
+        const words = command.split(/\s+/);
+        const packages = words.slice(words.indexOf('install') + 1).filter(w => !w.startsWith('-') && !w.includes('/') && !w.includes('='));
+        if (packages.length)
+            out.push({ packages: packages.slice(0, 6), sudo: true });
+    }
+    return out.slice(-4);
+}
+/**
+ * What the agent changed in the repositories in its home folder: uncommitted files, and commits made since the
+ * workspace was created ($1). The seeded project's own history is older and not counted.
+ */
+const GIT_CHANGES = 'for g in $(find /home/user -maxdepth 4 -name .git -type d 2>/dev/null); do d=${g%/.git}; git -C "$d" status --porcelain 2>/dev/null | sed "s/^/F /"; git -C "$d" log --since="$1" --format="C %H" 2>/dev/null; done; true';
+export function gitChanges(output) {
+    const lines = output.split('\n');
+    return { files: new Set(lines.filter(l => l.startsWith('F ')).map(l => l.slice(2))).size, commits: new Set(lines.filter(l => l.startsWith('C '))).size };
+}
+/** The desktop's size and its visible browser windows with their titles (display :1, as the computer tool uses it). */
+const DESKTOP_WINDOWS = 'export DISPLAY=:1; xdotool getdisplaygeometry 2>/dev/null || exit 0; for w in $(xdotool search --onlyvisible --class "chrom|firefox" 2>/dev/null); do xdotool getwindowgeometry --shell "$w"; printf "NAME=%s\\n" "$(xdotool getwindowname "$w" | tr -d "\\n")"; done; true';
+export function desktopWindows(output) {
+    const lines = output.trim().split('\n');
+    const size = lines[0]?.match(/^(\d+) (\d+)$/);
+    if (!size)
+        return { screen: null, browser: null };
+    const screen = { width: Number(size[1]), height: Number(size[2]) };
+    let browser = null;
+    for (const block of lines.slice(1).join('\n').split(/^WINDOW=/m).slice(1)) {
+        const value = (name) => Number(block.match(new RegExp(`^${name}=(-?\\d+)$`, 'm'))?.[1] ?? NaN);
+        const window = { x: value('X'), y: value('Y'), width: value('WIDTH'), height: value('HEIGHT'), title: (block.match(/^NAME=(.*)$/m)?.[1] ?? '').slice(0, 200) };
+        if (![window.x, window.y, window.width, window.height].every(Number.isFinite) || window.width < 200 || window.height < 150)
+            continue;
+        if (!browser || window.width * window.height > browser.width * browser.height)
+            browser = window;
+    }
+    return { screen, browser };
+}
+/** "/usr/local/bin/node server.mjs" reads as "node server.mjs"; long arguments are cut. */
+export function commandLine(argv) {
+    const [first = '', ...rest] = argv;
+    return [basename(first), ...rest].join(' ').replace(/\s+/g, ' ').trim().slice(0, 120);
+}
+/** Listening sockets with their processes (`ss`), else /proc/net/tcp{,6} on an image without it. */
+const LISTENERS = 'command -v ss >/dev/null && exec ss -ltnp; exec cat /proc/net/tcp /proc/net/tcp6';
+/**
+ * The computer's own listeners, not the agent's work: Codex Cloud's exec server and executor (staging: :43920 and
+ * :43922 in every Codex conversation), the guest agent and the desktop.
+ */
+const HARNESS_LISTENERS = new Set(['codex', 'sf-agent', 'sf-guest-agent', 'Xvnc']);
+/** Listening TCP ports from `ss -ltnp` or /proc/net/tcp{,6}, without the harness's or the desktop viewer's own ports. */
+export function listeningPorts(output) {
+    const ports = new Set();
+    for (const line of output.split('\n')) {
+        const fields = line.trim().split(/\s+/);
+        let port;
+        if (fields[0] === 'LISTEN') {
+            const owner = line.match(/users:\(\("([^"]+)"/)?.[1];
+            if (owner && HARNESS_LISTENERS.has(owner))
+                continue;
+            port = parseInt(fields[3]?.split(':').pop() ?? '', 10);
+        }
+        else {
+            if (fields[3] !== '0A')
+                continue;
+            port = parseInt(fields[1]?.split(':').pop() ?? '', 16);
+        }
+        if (port >= 1024 && port < 49152 && !(port >= 5900 && port < 6000) && port !== 6080)
+            ports.add(port);
+    }
+    return [...ports].sort((a, b) => a - b).slice(0, 4);
+}

package/dist/terminal-brand.d.ts

@@ -0,0 +1,5 @@
+export declare const terminalBrand: {
+    readonly "sf-ink": readonly [237, 235, 231];
+    readonly "sf-overlay": readonly [27, 28, 31];
+    readonly "sf-molten": readonly [255, 138, 61];
+};

package/dist/terminal-brand.js

@@ -0,0 +1,18 @@
+// Generated by scripts/sync-terminal-brand.mjs from brand/tokens.css.
+export const terminalBrand = {
+    "sf-ink": [
+        237,
+        235,
+        231
+    ],
+    "sf-overlay": [
+        27,
+        28,
+        31
+    ],
+    "sf-molten": [
+        255,
+        138,
+        61
+    ]
+};