@shardflux/cli 0.14.4 → 0.15.0

package/dist/credential-prompts.js

@@ -21,12 +21,20 @@ export class SiteVaultStore {
             throw new UsageError('Could not read site vault choices.');
         return raw;
     }
-    get(api, project, site) {
-        return this.read()[this.key(api, project, site)];
+    get(api, project, site, profile) {
+        const all = this.read();
+        return all[this.key(api, project, site)] ?? (profile ? all[this.key(api, `machine:${profile}`, site)] : undefined);
     }
-    save(api, project, site, selection) {
+    save(api, project, site, selection, profile) {
         const all = this.read();
-        all[this.key(api, project, site)] = selection;
+        if (selection.scope === 'machine') {
+            if (!profile)
+                throw new UsageError('Sign in or save a project profile before choosing machine scope.');
+            delete all[this.key(api, project, site)];
+            all[this.key(api, `machine:${profile}`, site)] = selection;
+        }
+        else
+            all[this.key(api, project, site)] = selection;
         mkdirSync(join(this.file, '..'), { recursive: true, mode: 0o700 });
         const temp = `${this.file}.${process.pid}.tmp`;
         writeFileSync(temp, JSON.stringify(all), { mode: 0o600, flag: 'wx' });
@@ -34,9 +42,20 @@ export class SiteVaultStore {
         chmodSync(this.file, 0o600);
     }
 }
+function vaultProfile(ctx) {
+    const profile = ctx.store.profile(ctx.apiUrl);
+    return profile.organization_id ? `org:${profile.organization_id}${profile.session?.user?.id ? `|user:${profile.session.user.id}` : ""}` : profile.session?.user?.id ? `user:${profile.session.user.id}` : profile.api_key?.key_id ? `key:${profile.api_key.key_id}` : undefined;
+}
+function approvalScope(value) {
+    if (value !== undefined && !['ask', 'project', 'machine'].includes(value))
+        throw new UsageError('--scope must be ask, project or machine');
+    return value;
+}
 export async function approveCredential(ctx, request, selection, remember = false) {
     if (request.state !== 'pending' || Date.parse(request.expires_at) <= Date.now())
         throw new UsageError(`Credential request ${request.id} has expired or ended. ${VAULT_SECURITY_NOTE}`);
+    if (selection.scope === 'machine' && !vaultProfile(ctx))
+        throw new UsageError('Sign in or save a project profile before choosing machine scope.');
     const credential = await vaultCredential(selection.vault, selection.item, request.site, { signal: ctx.signal });
     for (const value of Object.values(credential))
         if (typeof value === 'string' && value)
@@ -50,8 +69,8 @@ export async function approveCredential(ctx, request, selection, remember = fals
     if (answered.state !== 'fulfilled')
         throw new UsageError(`Credential request is ${answered.state}. ${VAULT_SECURITY_NOTE}`);
     if (remember)
-        await ctx.cloud().credentialRequests.remember(request.workspace_id, request.site, credential);
-    new SiteVaultStore(ctx.store.dir).save(ctx.apiUrl, request.project_id, request.site, selection);
+        await ctx.cloud().credentialRequests.remember(request.workspace_id, request.site, subset, selection.scope ? { scope: selection.scope === 'ask' ? 'conversation' : selection.scope } : {});
+    new SiteVaultStore(ctx.store.dir).save(ctx.apiUrl, request.project_id, request.site, { ...selection, always: selection.scope ? selection.scope !== 'ask' : selection.always, remember }, vaultProfile(ctx));
     ctx.io.stderr.write(`Approved ${request.site}. ${remember ? REMEMBERED_SECURITY_NOTE : VAULT_SECURITY_NOTE}\n`);
 }
 export async function configureCredentialFill(ctx, ws) {
@@ -88,23 +107,23 @@ export async function watchCredentialPrompts(ctx, ws, ask, signal) {
                 continue;
             seen.add(r.id);
             try {
-                const saved = store.get(ctx.apiUrl, r.project_id, r.site);
-                if (saved?.always && r.fields.every((f) => saved.fields.includes(f))) {
-                    await approveCredential(ctx, r, saved);
+                const saved = store.get(ctx.apiUrl, r.project_id, r.site, vaultProfile(ctx));
+                if (saved && (saved.scope ? saved.scope !== 'ask' : saved.always) && r.fields.every((f) => saved.fields.includes(f))) {
+                    await approveCredential(ctx, r, saved, saved.remember);
                     continue;
                 }
-                const choice = (await ask(`${r.site} requests ${r.fields.join(', ')}. Allow once / Always for this project / Deny [once/always/deny]. ${VAULT_SECURITY_NOTE}\n`)).toLowerCase();
+                const choice = (await ask(`${r.site} requests ${r.fields.join(', ')}. Ask every time / Allow for this project / Allow on my machine / Deny [once/project/machine/deny]. ${VAULT_SECURITY_NOTE}\n`)).toLowerCase();
                 if (choice === 'deny') {
                     await ctx.cloud().credentialRequests.deny(r.id);
                     ctx.io.stderr.write(`Denied ${r.site}. ${VAULT_SECURITY_NOTE}\n`);
                     continue;
                 }
-                if (choice !== 'once' && choice !== 'always')
-                    throw new UsageError(`Choose once, always or deny. ${VAULT_SECURITY_NOTE}`);
+                if (!['once', 'always', 'project', 'machine'].includes(choice))
+                    throw new UsageError(`Choose once, project, machine or deny. ${VAULT_SECURITY_NOTE}`);
                 const vault = vaultType(saved?.vault ?? (await ask(`Choose hsec, 1password, bitwarden or keychain. ${VAULT_SECURITY_NOTE}\n`)));
                 const item = saved?.item ?? (await ask(`Vault item name for ${r.site}. ${VAULT_SECURITY_NOTE}\n`));
                 const remember = (await ask(`Remember for unattended use? [yes/no]. ${REMEMBERED_SECURITY_NOTE}\n`)).toLowerCase() === 'yes';
-                await approveCredential(ctx, r, { vault, item, always: choice === 'always', fields: r.fields }, remember);
+                await approveCredential(ctx, r, { vault, item, always: choice !== 'once', scope: choice === 'once' ? 'ask' : choice === 'machine' ? 'machine' : 'project', fields: r.fields }, remember);
             }
             catch (e) {
                 if (signal.aborted)
@@ -162,7 +181,7 @@ export const CREDENTIAL_HANDLERS = {
         const item = str(values.item);
         if (!item)
             throw new UsageError('--item names a vault login');
-        await approveCredential(ctx, request, { vault, item, always: values.always === true, fields: request.fields }, values.remember === true);
+        await approveCredential(ctx, request, { vault, item, always: values.always === true || ['project', 'machine'].includes(str(values.scope) ?? ''), scope: approvalScope(str(values.scope)), fields: request.fields }, values.remember === true);
         if (ctx.json)
             ctx.io.stdout.write(JSON.stringify({
                 approved: true,
@@ -178,9 +197,12 @@ export const CREDENTIAL_HANDLERS = {
             : `Credential request ${r.state}. ${VAULT_SECURITY_NOTE}\n`);
         return 0;
     },
-    async 'credentials forget'(ctx, _values, [ref, site]) {
+    async 'credentials forget'(ctx, values, [ref, site]) {
         const ws = await resolveWorkspace(ctx, ref);
-        await ctx.cloud().credentialRequests.forget(ws.id, site);
+        const scope = str(values.scope);
+        if (scope && !['conversation', 'project', 'machine'].includes(scope))
+            throw new UsageError('--scope must be conversation, project or machine');
+        await ctx.cloud().credentialRequests.forget(ws.id, site, { scope: scope });
         ctx.io.stdout.write(ctx.json
             ? JSON.stringify({
                 forgotten: true,

package/dist/device-bridge.d.ts

@@ -31,6 +31,14 @@ export interface DeviceApproval {
     conversation_id: string;
     summary: string;
     outside: boolean;
+    kind?: DeviceRequest['kind'];
+    argv?: string[];
+    local_path?: string;
+    remote_path?: string;
+    project_name?: string;
+    conversation_title?: string;
+    local_port?: number;
+    remote_port?: number;
 }
 type Result = {
     state: 'approved' | 'denied' | 'running' | 'done' | 'failed';
@@ -56,6 +64,11 @@ export declare class DeviceGrants {
     save(api: string, project: string, root: string, kind: string): Promise<void>;
 }
 export declare function deviceSummary(r: DeviceRequest): string;
+/** Structured local approval details; the summary remains for older menu bar and ACP clients. */
+export declare function deviceApproval(r: DeviceRequest, c: Conversation, target: {
+    path: string;
+    outside: boolean;
+}, folder: string): DeviceApproval;
 export declare function tryLocallyAction(r: DeviceRequest): 'start' | 'stop' | null;
 export declare function ensureConversationWorktree(ctx: Ctx, c: Conversation, folder: string, ws?: Workspace): Promise<string>;
 export declare function deviceExec(argv: string[], cwd: string, timeoutSeconds?: number, signal?: AbortSignal): Promise<Result>;

package/dist/device-bridge.js

@@ -3,7 +3,7 @@ import { spawn } from 'node:child_process';
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync } from 'node:fs';
 import { readFile, writeFile, mkdir, realpath, stat } from 'node:fs/promises';
 import { createConnection, createServer } from 'node:net';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { WorkspaceTunnels } from '@shardflux/sdk';
 import { writePrivateFile } from "./credentials.js";
 import { conversationName, conversationWorkspace, getConversation, localConversations } from "./conversations.js";
@@ -73,8 +73,18 @@ export function deviceSummary(r) {
     if (r.kind === 'exec')
         return `Run on your Mac: ${JSON.stringify(r.exec?.argv)} · directory ${r.exec?.cwd_relative ?? '.'}`;
     if (r.files)
-        return `${r.kind === 'files_pull' ? 'Send to VM' : 'Save on your Mac'}: ${r.files.local_path_relative} ↔ ${r.files.remote_path}`;
-    return `${r.kind === 'port_forward' ? 'Open VM port on your Mac' : 'Reach your Mac from VM'}: ${r.port?.remote_port} ↔ localhost:${r.port?.local_port}`;
+        return `${r.kind === 'files_pull' ? 'Share with conversation' : 'Save on your Mac'}: ${r.files.local_path_relative} ↔ ${r.files.remote_path}`;
+    return `${r.kind === 'port_forward' ? 'Open conversation preview on your Mac' : 'Connect conversation to your Mac'}: ${r.port?.remote_port} ↔ localhost:${r.port?.local_port}`;
+}
+/** Structured local approval details; the summary remains for older menu bar and ACP clients. */
+export function deviceApproval(r, c, target, folder) {
+    return {
+        type: 'approval', request_id: r.id, project_id: r.project_id, conversation_id: c.id,
+        summary: deviceSummary(r), outside: target.outside, kind: r.kind, local_path: target.path,
+        project_name: basename(folder), conversation_title: c.title || conversationName(c),
+        ...(r.exec ? { argv: r.exec.argv } : {}), ...(r.files ? { remote_path: r.files.remote_path } : {}),
+        ...(r.port ? { local_port: r.port.local_port, remote_port: r.port.remote_port } : {}),
+    };
 }
 export function tryLocallyAction(r) {
     if (r.kind === 'try_locally')
@@ -172,7 +182,7 @@ export class DeviceExecutor {
         const requested = r.exec?.cwd_relative ?? r.files?.local_path_relative ?? '.';
         const target = devicePath(planned.path, requested), grants = new DeviceGrants(ctx.store.dir);
         target.outside ||= planned.outside;
-        const choice = grants.allows(ctx.apiUrl, r.project_id, record.folder, r.kind, target.outside) ? 'once' : await this.#ask({ type: 'approval', request_id: r.id, project_id: r.project_id, conversation_id: c.id, summary: deviceSummary(r), outside: target.outside });
+        const choice = grants.allows(ctx.apiUrl, r.project_id, record.folder, r.kind, target.outside) ? 'once' : await this.#ask(deviceApproval(r, c, target, record.folder));
         if (choice === 'deny') {
             await this.result(r, { state: 'denied' });
             return;

package/dist/device-helper.js

@@ -46,7 +46,8 @@ export async function runDeviceHelper(ctx) {
             ctx.io.stdout.write(JSON.stringify(approval) + '\n');
             if (signal.aborted)
                 denied();
-        });
+        }).finally(() => { if (!signal.aborted)
+            ctx.io.stdout.write(JSON.stringify({ type: 'approval_resolved', request_id: approval.request_id }) + '\n'); });
     };
     const working = new Map();
     const mirrored = new ConversationMirrorState();

package/dist/errors.d.ts

@@ -45,6 +45,15 @@ export declare class CodedError extends HintedError {
     readonly details: Record<string, unknown> | undefined;
     constructor(code: string, message: string, hint?: string, details?: Record<string, unknown>);
 }
+/**
+ * A command that can create an account ran without the agreement to the Terms of Service (0.15.0+): no
+ * --accept-terms / SHARDFLUX_ACCEPT_TERMS=1 and no terminal to ask on, or the person answered no. Nothing was sent.
+ * Code `terms_not_accepted`, exit 2 (usage); `details` has both links and the flag.
+ */
+export declare class TermsNotAcceptedError extends CodedError {
+    name: string;
+    constructor(declined?: boolean);
+}
 /** No usable credential: SHARDFLUX_API_KEY / the saved key, or the session, missing or malformed (never carries it). */
 export declare class AuthConfigError extends HintedError {
     name: string;

package/dist/errors.js

@@ -66,6 +66,19 @@ export class CodedError extends HintedError {
         this.details = details;
     }
 }
+/**
+ * A command that can create an account ran without the agreement to the Terms of Service (0.15.0+): no
+ * --accept-terms / SHARDFLUX_ACCEPT_TERMS=1 and no terminal to ask on, or the person answered no. Nothing was sent.
+ * Code `terms_not_accepted`, exit 2 (usage); `details` has both links and the flag.
+ */
+export class TermsNotAcceptedError extends CodedError {
+    name = 'TermsNotAcceptedError';
+    constructor(declined = false) {
+        super('terms_not_accepted', declined
+            ? 'Not signed up: creating an account needs your agreement to the Terms of Service and Privacy Policy.'
+            : 'Re-run with --accept-terms to agree to the Terms of Service (https://shardflux.dev/terms) and Privacy Policy (https://shardflux.dev/privacy); creating an account needs that agreement.', 'read https://shardflux.dev/terms and https://shardflux.dev/privacy, then re-run with --accept-terms (or set SHARDFLUX_ACCEPT_TERMS=1)', { terms_url: 'https://shardflux.dev/terms', privacy_url: 'https://shardflux.dev/privacy', flag: '--accept-terms' });
+    }
+}
 /** No usable credential: SHARDFLUX_API_KEY / the saved key, or the session, missing or malformed (never carries it). */
 export class AuthConfigError extends HintedError {
     name = 'AuthConfigError';
@@ -139,7 +152,7 @@ export class ExecSessionRunningError extends HintedError {
         this.session = session;
     }
 }
-const AUTH_CODES = new Set(['unauthenticated', 'invalid_credentials', 'token_invalid', 'forbidden', 'mfa_required', 'email_unverified', 'step_up_required', 'csrf_failed']);
+const AUTH_CODES = new Set(['unauthenticated', 'invalid_credentials', 'token_invalid', 'forbidden', 'mfa_required', 'email_unverified', 'step_up_required', 'csrf_failed', 'access_denied', 'expired_token']);
 const KEY_PATTERN = /sfk_[A-Za-z0-9]{8,}_[A-Za-z0-9]+/g;
 /** User session tokens (`sfu_` + 43 base64url characters), also cut short. */
 const SESSION_PATTERN = /sfu_[A-Za-z0-9_-]{16,}/g;
@@ -261,7 +274,7 @@ export function describeError(err) {
 export function exitCodeFor(err, interrupted = false) {
     if (interrupted || err instanceof InterruptedError)
         return EXIT.interrupted;
-    if (err instanceof UsageError || err instanceof TemplateFileError)
+    if (err instanceof UsageError || err instanceof TemplateFileError || err instanceof TermsNotAcceptedError)
         return EXIT.usage;
     if (err instanceof AuthConfigError || err instanceof MfaPendingError)
         return EXIT.auth;

package/dist/handlers.js

@@ -15,4 +15,5 @@ import { MENUBAR_HANDLERS } from "./menubar.js";
 import { UPDATE_HANDLERS } from "./update.js";
 import { FILESYSTEM_HANDLERS } from "./filesystem-commands.js";
 import { CONVERSATION_HANDLERS as LOCAL_CONVERSATION_HANDLERS } from "./conversation-local.js";
-export const HANDLERS = { ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };
+import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
+export const HANDLERS = { ...CODEX_CLOUD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };

package/dist/initial-prompt.d.ts

@@ -0,0 +1,26 @@
+import type { Ctx } from './commands.js';
+import type { Values } from './args.js';
+import type { TerminalConnection } from './agent-terminal.js';
+import type { CellClient } from '@shardflux/sdk';
+/** The user chose this repository. Trust exactly that new VM worktree before launching Codex's first turn. */
+export declare function prepareInitialCodexProject(cell: CellClient, cwd: string, ptyId: string): Promise<void>;
+export declare function readInitialPrompt(ctx: Ctx, values: Values): Promise<string | undefined>;
+/** Images for a new conversation's first message. They are held in memory and written only into the conversation VM. */
+export interface InitialImage {
+    path: string;
+    data: Uint8Array;
+    type: 'png' | 'jpeg' | 'gif' | 'webp';
+}
+export declare const ATTACHMENT_DIR = "/home/user/.shardflux/attachments";
+export declare const MAX_INITIAL_IMAGES = 5;
+export declare const MAX_INITIAL_IMAGE_BYTES: number;
+/** Standard input may carry several PNG files back to back (the menu bar's in-memory captures). */
+export declare function splitImages(data: Uint8Array): Uint8Array[];
+/** Reads and validates `--image <file|->` before any VM is allocated. */
+export declare function readInitialImages(ctx: Ctx, values: Values, prompt: string | undefined): Promise<InitialImage[]>;
+/** One VM path per line: Claude Code attaches each as an image when the prompt is pasted; Codex opens it with view_image. */
+export declare function promptWithImages(prompt: string, images: readonly InitialImage[]): string;
+/** Writes the images into the conversation VM before the first message refers to them. */
+export declare function uploadInitialImages(cell: Pick<CellClient, 'files'>, images: readonly InitialImage[], signal?: AbortSignal): Promise<void>;
+/** Wait for the native terminal to enable paste before submitting one first turn. No blind timing or input replay. */
+export declare function submitInitialPrompt(connect: (signal: AbortSignal) => Promise<TerminalConnection>, prompt: string, workspaceKey: string, signal: AbortSignal, app?: 'claude' | 'codex', write?: (bytes: Uint8Array) => Promise<unknown>): Promise<void>;

package/dist/initial-prompt.js

@@ -0,0 +1,196 @@
+import { randomUUID } from 'node:crypto';
+import { readInput, str, strs } from "./commands.js";
+import { PtyOutputCursor } from "./agent-terminal.js";
+import { CodedError, UsageError } from "./errors.js";
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { parse, stringify } from 'smol-toml';
+/** The user chose this repository. Trust exactly that new VM worktree before launching Codex's first turn. */
+export async function prepareInitialCodexProject(cell, cwd, ptyId) {
+    const path = '/home/user/.codex/config.toml';
+    let source = '', revision = 'absent';
+    try {
+        const old = await cell.files.readWithInfo(path);
+        source = new TextDecoder().decode(old.data);
+        if (!old.revision)
+            throw new Error('Codex config omitted its revision.');
+        revision = old.revision;
+    }
+    catch (error) {
+        if (!(error instanceof ShardfluxApiError && error.status === 404))
+            throw error;
+    }
+    const doc = parse(source);
+    const projects = doc.projects && typeof doc.projects === 'object' && !Array.isArray(doc.projects) ? doc.projects : {};
+    projects[cwd] = { ...(projects[cwd] ?? {}), trust_level: 'trusted' };
+    doc.projects = projects;
+    // The VM image owns Codex's version. An interactive updater must not intercept the first task.
+    doc.check_for_update_on_startup = false;
+    await cell.files.mkdir('/home/user/.codex', { parents: true });
+    await cell.files.patch({ path, content: stringify(doc), expectedRevision: revision, mode: '0600' });
+    // A new conversation's VM can auto-start its empty terminal before the CLI seeds/configures it.
+    // Reload that owned, never-prompted terminal so startup reads the chosen worktree's trust setting.
+    try {
+        const session = await cell.pty.get(ptyId);
+        if (session.state === 'running' || session.state === 'starting')
+            await cell.pty.close(ptyId);
+    }
+    catch (error) {
+        if (!(error instanceof ShardfluxApiError && error.status === 404))
+            throw error;
+    }
+}
+export async function readInitialPrompt(ctx, values) {
+    const prompt = str(values.prompt), file = str(values['prompt-file']);
+    if (prompt !== undefined && file !== undefined)
+        throw new UsageError('Use --prompt or --prompt-file, not both.');
+    const text = file === undefined ? prompt : new TextDecoder('utf-8', { fatal: true }).decode(await readInput(ctx, file, 262144, '--prompt-file'));
+    if (text !== undefined && (!text.trim() || text.includes('\0') || text.includes('\x1b') || Buffer.byteLength(text) > 262144)) {
+        throw new UsageError('The initial prompt must contain text, be at most 256 KiB, and contain no NUL or terminal escape characters.');
+    }
+    if (text !== undefined && values.resume === true)
+        throw new UsageError('An initial prompt is for a new conversation; use conversations send for an existing conversation.');
+    return text;
+}
+export const ATTACHMENT_DIR = '/home/user/.shardflux/attachments';
+export const MAX_INITIAL_IMAGES = 5;
+export const MAX_INITIAL_IMAGE_BYTES = 10 << 20;
+const PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+function imageType(data) {
+    const ascii = (from, to) => Buffer.from(data.subarray(from, to)).toString('latin1');
+    if (PNG.every((b, i) => data[i] === b))
+        return 'png';
+    if (data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff)
+        return 'jpeg';
+    if (ascii(0, 6) === 'GIF87a' || ascii(0, 6) === 'GIF89a')
+        return 'gif';
+    if (ascii(0, 4) === 'RIFF' && ascii(8, 12) === 'WEBP')
+        return 'webp';
+    return undefined;
+}
+/** Standard input may carry several PNG files back to back (the menu bar's in-memory captures). */
+export function splitImages(data) {
+    if (imageType(data) !== 'png')
+        return [data];
+    const images = [];
+    let start = 0;
+    while (start < data.length) {
+        if (!PNG.every((b, i) => data[start + i] === b))
+            throw new UsageError('--image -: standard input must be one image or PNG images back to back.');
+        let at = start + 8, end = 0;
+        while (!end) {
+            if (at + 12 > data.length)
+                throw new UsageError('--image -: a PNG image on standard input is truncated.');
+            const length = Buffer.from(data.subarray(at, at + 4)).readUInt32BE(0);
+            const type = Buffer.from(data.subarray(at + 4, at + 8)).toString('latin1');
+            at += 12 + length;
+            if (at > data.length)
+                throw new UsageError('--image -: a PNG image on standard input is truncated.');
+            if (type === 'IEND')
+                end = at;
+        }
+        images.push(data.subarray(start, end));
+        start = end;
+    }
+    return images;
+}
+/** Reads and validates `--image <file|->` before any VM is allocated. */
+export async function readInitialImages(ctx, values, prompt) {
+    const sources = strs(values.image);
+    if (!sources.length)
+        return [];
+    if (prompt === undefined)
+        throw new UsageError('--image needs an initial prompt: add --prompt or --prompt-file.');
+    if (sources.filter(s => s === '-').length > 1)
+        throw new UsageError('Use --image - once; standard input may carry several PNG images back to back.');
+    if (sources.includes('-') && str(values['prompt-file']) === '-')
+        throw new UsageError('--prompt-file - and --image - both read standard input. Pass one of them as a file.');
+    const id = randomUUID();
+    const images = [];
+    for (const source of sources) {
+        const data = await readInput(ctx, source, MAX_INITIAL_IMAGES * MAX_INITIAL_IMAGE_BYTES, '--image');
+        for (const part of source === '-' ? splitImages(data) : [data]) {
+            const type = imageType(part);
+            if (!type)
+                throw new UsageError(`--image ${source}: use a PNG, JPEG, GIF or WebP image.`);
+            if (part.length > MAX_INITIAL_IMAGE_BYTES)
+                throw new UsageError(`--image ${source}: each image must be at most ${MAX_INITIAL_IMAGE_BYTES >> 20} MiB.`);
+            if (images.length === MAX_INITIAL_IMAGES)
+                throw new UsageError(`Attach at most ${MAX_INITIAL_IMAGES} images.`);
+            images.push({ path: `${ATTACHMENT_DIR}/${id}-${images.length + 1}.${type === 'jpeg' ? 'jpg' : type}`, data: part, type });
+        }
+    }
+    return images;
+}
+/** One VM path per line: Claude Code attaches each as an image when the prompt is pasted; Codex opens it with view_image. */
+export function promptWithImages(prompt, images) {
+    if (!images.length)
+        return prompt;
+    const text = `${prompt}\n\nAttached ${images.length === 1 ? 'image' : 'images'} (view ${images.length === 1 ? 'it' : 'each one'} before you start):\n${images.map(i => i.path).join('\n')}`;
+    if (Buffer.byteLength(text) > 262144)
+        throw new UsageError('The initial prompt with its image references must be at most 256 KiB.');
+    return text;
+}
+/** Writes the images into the conversation VM before the first message refers to them. */
+export async function uploadInitialImages(cell, images, signal) {
+    for (const image of images) {
+        signal?.throwIfAborted();
+        await cell.files.write(image.path, image.data, { mode: '0600', createParents: true });
+    }
+}
+/** Wait for the native terminal to enable paste before submitting one first turn. No blind timing or input replay. */
+export async function submitInitialPrompt(connect, prompt, workspaceKey, signal, app = 'claude', write) {
+    const bounded = AbortSignal.any([signal, AbortSignal.timeout(20000)]);
+    let connection;
+    let sent = false, pasted = false;
+    try {
+        connection = await connect(bounded);
+        let tail = '', pasteEnabled = false;
+        const cursor = new PtyOutputCursor();
+        for await (const message of connection.messages()) {
+            if (bounded.aborted)
+                throw bounded.reason;
+            if (message.type === 'exit')
+                throw new Error('The agent exited before accepting a prompt.');
+            const bytes = cursor.consume(message);
+            if (!bytes)
+                continue;
+            tail = (tail + bytes.toString('utf8')).slice(-32768);
+            pasteEnabled ||= tail.includes('\x1b[?2004h');
+            // eslint-disable-next-line no-control-regex -- Strip native terminal ANSI before matching prompt echo.
+            const plain = tail.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/\s/g, '');
+            if (sent && bytes.length)
+                return;
+            if (pasted) {
+                // A long prompt overflows the input box: a 24-row terminal shows only its end, so either end confirms the paste.
+                const compact = prompt.replace(/\s/g, '');
+                if (!plain.includes(compact.slice(0, 32)) && !plain.includes(compact.slice(-32)) && !/Pasted(?:text|content)/i.test(plain))
+                    continue;
+                const enter = Buffer.from('\r');
+                if (write)
+                    await write(enter);
+                else
+                    connection.input(enter);
+                sent = true;
+                tail = '';
+                continue;
+            }
+            const ready = app === 'claude' ? tail.includes('❯') : tail.includes('›');
+            if (!ready || !pasteEnabled)
+                continue;
+            const paste = Buffer.from(`\x1b[200~${prompt}\x1b[201~`);
+            if (write)
+                await write(paste);
+            else
+                connection.input(paste);
+            pasted = true;
+            tail = '';
+        }
+        throw new Error('The agent terminal closed before accepting a prompt.');
+    }
+    catch {
+        throw new CodedError('initial_prompt_failed', `Created ${workspaceKey}, but the initial prompt ${sent ? 'could not be confirmed' : 'was not submitted'}. Open that conversation before starting another.`, undefined, { workspace_key: workspaceKey, submitted: sent });
+    }
+    finally {
+        await connection?.close();
+    }
+}

package/dist/legal.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The Terms of Service notice and acceptance, one place for every sign-in and sign-up path (the dashboard's sign-up
+ * page and the Mac app show the same line).
+ *
+ * - Signing in to an existing account (a password, the browser) only shows the notice: one line on stderr before it
+ *   acts, or `terms_url` and `privacy_url` in the `--json` output for an app or agent to show.
+ * - A command that can create an account (`shard signup`, `shard auth register`, `shard auth login --codex`) needs the
+ *   agreement first: `--accept-terms` (or SHARDFLUX_ACCEPT_TERMS=1), or "Continue? [Y/n]" on a terminal. Without
+ *   either it stops before any network call with `terms_not_accepted` (exit 2), so an agent asks its person and
+ *   re-runs with the flag. The API records the agreement on the new account (`accept_terms`, `terms_version`).
+ */
+import type { Ctx } from './commands.js';
+import type { Values } from './args.js';
+export declare const TERMS_URL = "https://shardflux.dev/terms";
+export declare const PRIVACY_URL = "https://shardflux.dev/privacy";
+/** The published version of the terms: the effective date on the terms page. */
+export declare const TERMS_VERSION = "2026-09-28";
+export declare const ACCEPT_TERMS_FLAG = "--accept-terms";
+export declare const ACCEPT_TERMS_ENV = "SHARDFLUX_ACCEPT_TERMS";
+/** "By continuing, you agree to our Terms of Service (<url>) and acknowledge our Privacy Policy (<url>)." */
+export declare function legalNotice(): string;
+/** The two links in a command's `--json` output. */
+export declare function legalFields(): {
+    terms_url: string;
+    privacy_url: string;
+};
+/** The notice before a sign-in acts: a line on stderr (none in `--json`, where the output carries the links). */
+export declare function showLegalNotice(ctx: Ctx): void;
+/**
+ * The agreement before a command that can create an account, before any network call. Returns what the API records;
+ * throws TermsNotAcceptedError when there is none (no flag and no terminal to ask on, or the person said no).
+ */
+export declare function requireTermsAcceptance(ctx: Ctx, values: Values): Promise<{
+    acceptTerms: true;
+    termsVersion: string;
+}>;

package/dist/legal.js

@@ -0,0 +1,44 @@
+import { TermsNotAcceptedError } from "./errors.js";
+export const TERMS_URL = 'https://shardflux.dev/terms';
+export const PRIVACY_URL = 'https://shardflux.dev/privacy';
+/** The published version of the terms: the effective date on the terms page. */
+export const TERMS_VERSION = '2026-09-28';
+export const ACCEPT_TERMS_FLAG = '--accept-terms';
+export const ACCEPT_TERMS_ENV = 'SHARDFLUX_ACCEPT_TERMS';
+/** "By continuing, you agree to our Terms of Service (<url>) and acknowledge our Privacy Policy (<url>)." */
+export function legalNotice() {
+    return `By continuing, you agree to our Terms of Service (${TERMS_URL}) and acknowledge our Privacy Policy (${PRIVACY_URL}).`;
+}
+/** The two links in a command's `--json` output. */
+export function legalFields() {
+    return { terms_url: TERMS_URL, privacy_url: PRIVACY_URL };
+}
+/** The notice before a sign-in acts: a line on stderr (none in `--json`, where the output carries the links). */
+export function showLegalNotice(ctx) {
+    if (!ctx.json)
+        ctx.io.stderr.write(`${legalNotice()}\n`);
+}
+function acceptedUpFront(ctx, values) {
+    if (values['accept-terms'] === true)
+        return true;
+    const env = ctx.io.env[ACCEPT_TERMS_ENV]?.trim().toLowerCase();
+    return env === '1' || env === 'true' || env === 'yes';
+}
+/**
+ * The agreement before a command that can create an account, before any network call. Returns what the API records;
+ * throws TermsNotAcceptedError when there is none (no flag and no terminal to ask on, or the person said no).
+ */
+export async function requireTermsAcceptance(ctx, values) {
+    const accepted = { acceptTerms: true, termsVersion: TERMS_VERSION };
+    if (acceptedUpFront(ctx, values)) {
+        showLegalNotice(ctx);
+        return accepted;
+    }
+    if (!ctx.input.interactive || ctx.json)
+        throw new TermsNotAcceptedError();
+    ctx.io.stderr.write(`${legalNotice()}\n`);
+    const answer = (await ctx.input.answer('Continue? [Y/n] '))?.trim().toLowerCase() ?? '';
+    if (answer === '' || answer === 'y' || answer === 'yes')
+        return accepted;
+    throw new TermsNotAcceptedError(true);
+}

package/dist/main.js

@@ -18,6 +18,7 @@ import { commandCenter } from "./command-center.js";
 import { launchConversationProject } from "./conversation-terminal.js";
 import { runAcp } from "./acp.js";
 import { registerInstalledT3 } from "./t3-provider.js";
+import { runAcpLogin } from "./acp-login.js";
 import { runDeviceHelper } from "./device-helper.js";
 import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
 import { CredentialStore, configDir } from "./credentials.js";
@@ -84,6 +85,9 @@ function hintFor(info, cred, file, command = '') {
         return STEP_UP_HINT;
     if (info.code === 'mfa_required')
         return 'finish signing in with the code of your authenticator app: shard auth mfa --code <code>';
+    // The browser sign-in (0.15.0+): refused in the browser, or not approved within its 10 minutes.
+    if (info.code === 'access_denied' || info.code === 'expired_token')
+        return 'start the sign-in again: shard auth login --browser';
     if (info.code === 'email_unverified')
         return `verify your email first: shard auth verify-email '<link from the email>' (a new link: shard auth resend-verification)`;
     if (info.code === 'conflict' && reasonOf(info) === 'subscription_exists')
@@ -316,7 +320,7 @@ const FEEDBACK_EMAIL = 'shardflux@heliosone.fi';
  */
 // allowance_exhausted (0.5.1): a used-up allowance, a reached spend cap or a paused overage is a billing state whose hint
 // names the next step (upgrade, overage, the cap, the payment method), not a problem to report.
-const NO_NUDGE_CODES = new Set(['usage', 'interrupted', 'unauthenticated', 'validation_failed', 'mfa_required', 'step_up_required', 'email_unverified', 'timeout', 'checkout_ended', 'allowance_exhausted']);
+const NO_NUDGE_CODES = new Set(['usage', 'terms_not_accepted', 'interrupted', 'unauthenticated', 'validation_failed', 'mfa_required', 'step_up_required', 'email_unverified', 'timeout', 'checkout_ended', 'allowance_exhausted']);
 const NO_NUDGE_REASONS = new Set([
     'revision_mismatch',
     'tree_revision_mismatch',
@@ -644,7 +648,7 @@ export async function run(argv, io, opts = {}) {
     catch (err) {
         return report(err);
     }
-    const handler = parsed.command.path[0] === 'acp' ? (ctx) => runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? runDeviceHelper : parsed.command === PROJECT_COMMAND ? launchConversationProject : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
+    const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? runDeviceHelper : parsed.command === PROJECT_COMMAND ? launchConversationProject : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
     if (!handler)
         return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));
     if (!['acp', 'device-helper'].includes(parsed.command.path[0]))

package/dist/menubar.d.ts

@@ -1,5 +1,13 @@
 import type { Handler } from './commands.js';
 export type NativeRunner = (tool: string, args: string[]) => Promise<string>;
+/**
+ * Every native tool a default MenubarManager runs (plutil, codesign, xattr, open, the app's --control) goes through
+ * `nativeTools.run`. The CLI test support replaces it, so a test run never starts, stops or inspects a real app,
+ * whether or not a built Shardflux.app is in the package.
+ */
+export declare const nativeTools: {
+    run: (tool: string, args: string[], signal?: AbortSignal) => Promise<string>;
+};
 export interface MenubarStatus {
     installed: boolean;
     version: string | null;

package/dist/menubar.js

@@ -8,6 +8,14 @@ import { AgentStateStore } from "./agent-state.js";
 import { UsageError } from "./errors.js";
 import { json } from "./format.js";
 const execute = promisify(execFile);
+/**
+ * Every native tool a default MenubarManager runs (plutil, codesign, xattr, open, the app's --control) goes through
+ * `nativeTools.run`. The CLI test support replaces it, so a test run never starts, stops or inspects a real app,
+ * whether or not a built Shardflux.app is in the package.
+ */
+export const nativeTools = {
+    run: async (tool, args, signal) => (await execute(tool, args, { timeout: 15000, maxBuffer: 1024 * 1024, signal })).stdout,
+};
 const BUNDLE_ID = 'dev.shardflux.menubar';
 export function compareBundleVersions(left, right) {
     if (![left, right].every(v => /^\d+(\.\d+){0,3}$/.test(v)))
@@ -58,7 +66,7 @@ export class MenubarManager {
     constructor(options = {}) {
         this.app = join(options.home ?? homedir(), 'Applications', 'Shardflux.app');
         this.#platform = options.platform ?? process.platform;
-        this.#run = options.run ?? (async (tool, args) => (await execute(tool, args, { timeout: 15000, maxBuffer: 1024 * 1024, signal: options.signal })).stdout);
+        this.#run = options.run ?? ((tool, args) => nativeTools.run(tool, args, options.signal));
         this.#packageApp = options.packageApp ?? (() => {
             try {
                 return join(dirname(createRequire(import.meta.url).resolve('@shardflux/menubar-darwin/package.json')), 'Shardflux.app');