@shardflux/cli 0.14.5 → 0.15.0

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');

package/dist/onboarding-app/AGENTS.md

@@ -0,0 +1,19 @@
+# Daylight
+
+A small task list: `server.mjs` (a Node.js server with a JSON API) and `index.html`. No dependencies.
+
+## Run it
+
+- `npm run dev` serves it on port 3000 and restarts on save. It watches files with inotifywait from inotify-tools, a
+  system package: install it with `sudo apt-get install -y inotify-tools` if it is missing.
+- Open `http://localhost:3000` in the browser on your desktop (`DISPLAY=:1 setsid -f chromium http://localhost:3000`)
+  and use the computer tool to see and click it.
+
+## Test it
+
+Use it like a person: add a task, tick it off, and look at each view (All, Active, Completed). Leave the page open.
+
+## Report
+
+Reply with one short paragraph: what you started, what you clicked, and what works and what does not. Change code only
+if you are asked to.

package/dist/onboarding-app/CLAUDE.md

@@ -0,0 +1,19 @@
+# Daylight
+
+A small task list: `server.mjs` (a Node.js server with a JSON API) and `index.html`. No dependencies.
+
+## Run it
+
+- `npm run dev` serves it on port 3000 and restarts on save. It watches files with inotifywait from inotify-tools, a
+  system package: install it with `sudo apt-get install -y inotify-tools` if it is missing.
+- Open `http://localhost:3000` in the browser on your desktop (`DISPLAY=:1 setsid -f chromium http://localhost:3000`)
+  and use the computer tool to see and click it.
+
+## Test it
+
+Use it like a person: add a task, tick it off, and look at each view (All, Active, Completed). Leave the page open.
+
+## Report
+
+Reply with one short paragraph: what you started, what you clicked, and what works and what does not. Change code only
+if you are asked to.

package/dist/onboarding-app/README.md

@@ -0,0 +1,12 @@
+# Daylight
+
+A small full-stack task list: a Node.js server with a JSON API and one HTML page. No dependencies.
+
+```sh
+npm run dev    # serves on :3000 and reloads on save; needs inotify-tools (sudo apt-get install -y inotify-tools)
+```
+
+Open `http://localhost:3000`. Tasks live in memory while the server runs. Set `PORT` to use another port.
+
+Shardflux uses Daylight for its first-run demo, "Daylight (sample)": an agent installs what it needs, starts it and
+tests it in the browser on its own computer. `CLAUDE.md` and `AGENTS.md` tell Claude Code and Codex how.

package/dist/onboarding-app/dev.mjs

@@ -0,0 +1,18 @@
+// Dev server: runs server.mjs and restarts it when a source file is saved. Watches with inotifywait (inotify-tools).
+import { spawn, spawnSync } from 'node:child_process';
+
+if (spawnSync('inotifywait', ['--help'], { stdio: 'ignore' }).error) {
+  console.error('npm run dev watches files with inotifywait. Install it with: sudo apt-get install -y inotify-tools');
+  process.exit(1);
+}
+let server;
+const start = () => { server = spawn(process.execPath, ['server.mjs'], { stdio: 'inherit' }); };
+const restart = () => { console.log('Saved. Restarting Daylight…'); server.once('exit', start); server.kill(); };
+start();
+const watcher = spawn('inotifywait', ['-m', '-q', '-e', 'close_write,moved_to', '--format', '%f', '.'], { stdio: ['ignore', 'pipe', 'inherit'] });
+let timer;
+watcher.stdout.on('data', chunk => {
+  if (!/\.(mjs|html)\b/.test(String(chunk))) return;
+  clearTimeout(timer); timer = setTimeout(restart, 150);
+});
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => { watcher.kill(); server.kill(); process.exit(0); });

package/dist/onboarding-app/index.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Daylight · One good day</title>
+<style>
+:root{color-scheme:light;--paper:#f5f2ea;--ink:#282b27;--muted:#747970;--line:#deded3;--green:#3f614e;font-family:system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif}*{box-sizing:border-box}body{margin:0;background:var(--paper);color:var(--ink)}main{max-width:660px;margin:12vh auto;padding:24px}header{display:flex;align-items:center;justify-content:space-between}.wordmark{font-size:15px;font-weight:600;letter-spacing:-.2px}.dot{width:28px;height:28px;border:1px solid var(--green);border-radius:50%;display:inline-block;margin-right:12px;vertical-align:middle}.edition{font-size:12px;color:var(--muted)}h1{font-size:48px;line-height:1.05;font-weight:650;letter-spacing:-1.8px;margin:52px 0 14px}p{color:var(--muted);line-height:1.6}form{display:flex;gap:10px;margin:34px 0 32px}input[type=text]{flex:1;min-width:0;border:1px solid var(--line);border-radius:8px;padding:14px;background:#fffdf8;color:var(--ink);font:inherit}button{cursor:pointer;font:inherit;border:0;border-radius:7px;padding:11px 16px;background:var(--green);color:white}nav{display:flex;gap:6px;border-bottom:1px solid var(--line);padding-bottom:14px}nav button{background:transparent;color:var(--muted);font-size:13px;padding:8px 13px}nav button[aria-pressed=true]{background:#e1e7dc;color:var(--green)}ul{list-style:none;margin:0;padding:0;min-height:170px}li{display:flex;align-items:center;gap:14px;padding:21px 2px;border-bottom:1px solid var(--line)}li input{accent-color:var(--green);width:20px;height:20px;cursor:pointer}li label{flex:1}li.done label{text-decoration:line-through;color:var(--muted)}footer{display:flex;justify-content:space-between;font-size:12px;color:var(--muted);margin-top:24px}.empty{padding:35px 0;color:var(--muted)}#error{color:#a13b32;min-height:18px;font-size:13px}button:focus-visible,input:focus-visible{outline:2px solid var(--green);outline-offset:3px}@media(max-width:600px){main{margin:5vh auto}h1{font-size:44px}.edition{display:none}}
+</style>
+<main>
+<header><span class="wordmark"><span class="dot"></span>Daylight</span><span class="edition">A little room to get things done.</span></header>
+<h1>One thing at a time.</h1>
+<p>A short list. A clear head. Make room for a good day.</p>
+<form id="add"><input type="text" id="title" aria-label="New task" placeholder="What would you like to do?" maxlength="100" required><button>Add task</button></form>
+<nav aria-label="Task filters"><button type="button" data-view="all" aria-pressed="true">All</button><button type="button" data-view="active" aria-pressed="false">Active</button><button type="button" data-view="done" aria-pressed="false">Completed</button></nav>
+<ul id="tasks" aria-live="polite"></ul><div id="error" role="alert"></div>
+<footer><span id="remaining"></span><span>Small steps count.</span></footer>
+</main>
+<script type="module">
+let view='all';const list=document.querySelector('#tasks'),error=document.querySelector('#error');
+async function api(path,options){const response=await fetch(path,options);if(!response.ok)throw Error(await response.text());return response.json()}
+async function render(){try{const data=await api('/api/tasks?view='+view);list.replaceChildren();for(const task of data.tasks){const row=document.createElement('li');row.classList.toggle('done',task.done);const check=document.createElement('input');check.type='checkbox';check.checked=task.done;check.id='task-'+task.id;check.addEventListener('change',async()=>{try{await api('/api/tasks/'+task.id,{method:'PATCH'});await render()}catch(e){error.textContent=e.message}});const label=document.createElement('label');label.htmlFor=check.id;label.textContent=task.title;row.append(check,label);list.append(row)}if(!data.tasks.length){const empty=document.createElement('li');empty.className='empty';empty.textContent='Nothing here. Enjoy the space.';list.append(empty)}document.querySelector('#remaining').textContent=data.remaining+' left to do';error.textContent=''}catch(e){error.textContent=e.message}}
+document.querySelector('#add').addEventListener('submit',async e=>{e.preventDefault();try{await api('/api/tasks',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({title:document.querySelector('#title').value})});document.querySelector('#title').value='';await render()}catch(e){error.textContent=e.message}});
+for(const button of document.querySelectorAll('[data-view]'))button.addEventListener('click',()=>{view=button.dataset.view;for(const other of document.querySelectorAll('[data-view]'))other.setAttribute('aria-pressed',String(other===button));document.title=view==='all'?'Daylight · One good day':'Daylight · '+button.textContent;render()});render();
+</script>
+</html>

package/dist/onboarding-app/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "daylight",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node dev.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/dist/onboarding-app/server.mjs

@@ -0,0 +1,41 @@
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const tasks = [
+  { id: 1, title: 'Sketch the idea', done: true },
+  { id: 2, title: 'Build something useful', done: false },
+  { id: 3, title: 'Take a walk', done: false },
+];
+let nextID = 4;
+const server = createServer(async (req, res) => {
+  try {
+    const url = new URL(req.url, 'http://localhost');
+    if (url.pathname === '/api/tasks' && req.method === 'GET') {
+      const view = url.searchParams.get('view') || 'all';
+      const visible = view === 'active' ? tasks.filter(t => !t.done) : view === 'done' ? tasks.filter(t => !t.done) : tasks;
+      res.setHeader('Content-Type', 'application/json');
+      return res.end(JSON.stringify({ tasks: visible, remaining: tasks.filter(t => !t.done).length }));
+    }
+    if (url.pathname === '/api/tasks' && req.method === 'POST') {
+      let body = ''; for await (const part of req) { body += part; if (body.length > 4096) throw Error('Too much text'); }
+      const title = String(JSON.parse(body).title || '').trim();
+      if (!title || title.length > 100) { res.writeHead(400); return res.end('Use 1–100 characters.'); }
+      tasks.push({ id: nextID++, title, done: false }); res.writeHead(201); return res.end('{}');
+    }
+    const match = url.pathname.match(/^\/api\/tasks\/(\d+)$/);
+    if (match && req.method === 'PATCH') {
+      const task = tasks.find(t => t.id === Number(match[1]));
+      if (!task) { res.writeHead(404); return res.end('Task not found'); }
+      task.done = !task.done; return res.end('{}');
+    }
+    if (url.pathname === '/' && req.method === 'GET') {
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
+      return res.end(await readFile(new URL('./index.html', import.meta.url)));
+    }
+    res.writeHead(404); res.end('Not found');
+  } catch { res.writeHead(400); res.end('Could not read that request.'); }
+});
+const port = Number(process.env.PORT || 3000);
+if (process.argv[1] === fileURLToPath(import.meta.url)) server.listen(port, '0.0.0.0', () => console.log(`Daylight is running on http://0.0.0.0:${port}`));
+export { server };

package/dist/onboarding-sample.d.ts

@@ -0,0 +1,3 @@
+export declare function sampleSource(): Promise<string>;
+/** A private, fresh real Git project; never writes into the user's selected repository. */
+export declare function prepareOnboardingSample(directory: string): Promise<string>;

package/dist/onboarding-sample.js

@@ -0,0 +1,29 @@
+import { access, cp, mkdir, mkdtemp } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const execute = promisify(execFile);
+export async function sampleSource() {
+    for (const url of [new URL('./onboarding-app/', import.meta.url), new URL('../../../examples/onboarding-app/', import.meta.url)]) {
+        try {
+            await access(new URL('server.mjs', url));
+            return fileURLToPath(url);
+        }
+        catch { /* source tree or published bundle */ }
+    }
+    throw new Error('The onboarding app is missing. Reinstall the Shardflux CLI.');
+}
+/** A private, fresh real Git project; never writes into the user's selected repository. */
+export async function prepareOnboardingSample(directory) {
+    const root = join(directory, 'onboarding-projects');
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    // The folder's own name is what the launcher lists: "Daylight (sample)".
+    const path = join(await mkdtemp(join(root, 'sample-')), 'Daylight (sample)');
+    await cp(await sampleSource(), path, { recursive: true });
+    const git = (args) => execute('git', args, { cwd: path, timeout: 10000, env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1' } });
+    await git(['init', '-q', '-b', 'main']);
+    await git(['add', '.']);
+    await git(['-c', 'user.name=Shardflux', '-c', 'user.email=first-run@shardflux.dev', '-c', 'commit.gpgsign=false', 'commit', '-qm', 'Start Daylight onboarding app']);
+    return path;
+}