@shardflux/cli 0.25.0 → 0.28.1

package/dist/agent-commands.js

@@ -33,7 +33,7 @@ import { guestFirstPrompt, INBOX_MAX_CHARS, submitInitialPrompt, prepareInitialC
 import { conversationForOpen, conversationWorkspace, conversationsUnavailable, getConversation, listConversations, resumeConversation } from "./conversations.js";
 import { conversationClient } from "./conversation-commands.js";
 import { conversationTerminal, reopenConversation } from "./conversation-terminal.js";
-import { CHOICE_PENDING, choiceReport, hasChoice, launchChoice, modelChoice, runFlags } from "./agent-models.js";
+import { CHOICE_PENDING, choiceReport, hasChoice, launchChoice, liveModels, modelChoice, runFlags } from "./agent-models.js";
 const active = (session) => session.state === 'running' || session.state === 'starting';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
 export function disambiguatedSlug(slug, identity) {
@@ -135,7 +135,7 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
         });
         // This command's --model/--effort, else the conversation's own (a relaunch keeps its model). A computer whose guest
         // predates the choice starts the agent with its defaults, and this command says so once.
-        const help = runHelp(cell, app, ctx.signal), explicit = modelChoice(values, app);
+        const help = runHelp(cell, app, ctx.signal), explicit = modelChoice(values, app, await liveModels(ctx, values, app));
         const { choice, applied } = await launchChoice(explicit, conversation?.choice, !!conversation, help);
         if (hasChoice(explicit) && !applied && !ctx.json)
             ctx.io.stderr.write(`${CHOICE_PENDING}\n`);
@@ -242,7 +242,8 @@ export async function launchProjectWith(ctx, values, [path = './', explicitApp],
         throw new UsageError(`${target} is not an installed desktop target`);
     const app = explicitApp ?? store.app(projectKey, like?.labels.app === 'codex' ? 'codex' : 'claude');
     // A typo in --model or --effort is refused before anything starts; T3 Code reads the same values (0.17.0+).
-    const choice = modelChoice(values, target === 'codex-app' ? 'codex' : app);
+    const choiceApp = target === 'codex-app' ? 'codex' : app;
+    const choice = modelChoice(values, choiceApp, await liveModels(ctx, values, choiceApp));
     if (target === 'codex-app' || (app === 'codex' && !like && values.in === undefined && !linuxTerminalSession(ctx, values)))
         return launchCodexCloud(ctx, values, path);
     if (target === 'claude-desktop' && hasChoice(choice))

package/dist/agent-git-commands.d.ts

@@ -6,5 +6,4 @@ export declare function rememberGitAgent(ctx: Ctx, ws: Workspace, folder: string
 export declare const AGENT_GIT_HANDLERS: Record<string, Handler>;
 /** No Git or network work when no records are due. Active passes are bounded and never infer deletion from an error. */
 export declare function housekeeping(ctx: HousekeepingCtx, now?: () => number, budgetMs?: number): Promise<void>;
-/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
-export declare function startupHousekeeping(ctx: Pick<Ctx, 'io' | 'store' | 'signal'>): Promise<void>;
+export { startupHousekeeping } from './startup-housekeeping.js';

package/dist/agent-git-commands.js

@@ -1,9 +1,8 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { Shardflux, ShardfluxApiError } from '@shardflux/sdk';
+import { ShardfluxApiError } from '@shardflux/sdk';
 import { out, resolveWorkspace, str } from "./commands.js";
 import { AgentStateStore } from "./agent-state.js";
-import { resolveApiUrl } from "./args.js";
 import { AgentGit, agentName } from "./agent-git.js";
 import { shardRemote } from "./git-remote.js";
 import { projectIdentity } from "./project-identity.js";
@@ -274,22 +273,4 @@ export async function housekeeping(ctx, now = Date.now, budgetMs = 1500) {
         clearTimeout(timer);
     }
 }
-/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
-export async function startupHousekeeping(ctx) {
-    try {
-        const state = new AgentStateStore(ctx.store.dir).read();
-        if (!state.git_repositories || !Object.keys(state.git_repositories).length)
-            return;
-        const apiUrl = resolveApiUrl(undefined, ctx.io.env.SHARDFLUX_API_URL ?? ctx.io.env.SHARDFLUX_BASE_URL);
-        let cloud;
-        await housekeeping({ ...ctx, apiUrl, cloud: () => {
-                const key = ctx.io.env.SHARDFLUX_API_KEY?.trim() || ctx.store.profile(apiUrl).api_key?.token;
-                if (!key)
-                    throw new UsageError('saved agents need a project key for housekeeping; run shard setup');
-                return cloud ??= new Shardflux({ apiKey: key, baseUrl: apiUrl, versionCheck: false });
-            } });
-    }
-    catch (error) {
-        ctx.io.stderr.write(`shard housekeeping: ${error instanceof Error ? error.message : String(error)}\n`);
-    }
-}
+export { startupHousekeeping } from "./startup-housekeeping.js";

package/dist/agent-models.d.ts

@@ -30,13 +30,42 @@ export interface AppModels {
 export declare const DEFAULT_CHOICE = "default";
 /** Claude Code `--model <alias>` and `--effort <level>`; Codex `-m <model>` and `-c model_reasoning_effort=<level>`. */
 export declare const MODEL_CHOICES: Readonly<Record<ModelApp, AppModels>>;
+/** A model of the active account's live list (`shard agents models`, 0.27.0+): its id and the efforts it takes. */
+export interface LiveModel {
+    id: string;
+    efforts: string[];
+}
+interface ModelsSource {
+    cloud(): {
+        agentAccounts: {
+            allModels(opts: {
+                provider?: ModelApp;
+            }): Promise<{
+                accounts: Array<{
+                    active: boolean;
+                    models: Array<{
+                        id: string;
+                        efforts: string[];
+                        available: boolean;
+                    }>;
+                }>;
+            }>;
+        };
+    };
+}
+/**
+ * The active account's available models (0.27.0+), asked only when `--model` is not one of the aliases above: a full
+ * model id is accepted when the account's provider lists it (GET /v1/agent-accounts/models). Null when the API cannot
+ * say (an API before the route, or a failure): then only the aliases are accepted.
+ */
+export declare function liveModels(ctx: ModelsSource, values: Values, app: ModelApp): Promise<LiveModel[] | null>;
 /** What a thread starts with: absent fields are the agent's own default (no flag). */
 export interface ModelChoice {
     model?: string;
     effort?: string;
 }
 /** `--model` and `--effort` for this app, checked against its list. Throws a usage error for anything else. */
-export declare function modelChoice(values: Values, app: ModelApp): ModelChoice;
+export declare function modelChoice(values: Values, app: ModelApp, live?: readonly LiveModel[] | null): ModelChoice;
 export declare const hasChoice: (c: ModelChoice | undefined) => c is ModelChoice;
 /** The guest's `sf-agent run` flags for a choice (sf-agent maps them to the agent's own flags). */
 export declare function runFlags(c: ModelChoice | undefined): string[];
@@ -59,3 +88,4 @@ export declare function choiceReport(c: ModelChoice, applied: boolean): {
     effort: string;
     applied: boolean;
 };
+export {};

package/dist/agent-models.js

@@ -25,10 +25,31 @@ export const MODEL_CHOICES = {
         default: { model: 'gpt-6.1-sol', effort: null },
     },
 };
+/**
+ * The active account's available models (0.27.0+), asked only when `--model` is not one of the aliases above: a full
+ * model id is accepted when the account's provider lists it (GET /v1/agent-accounts/models). Null when the API cannot
+ * say (an API before the route, or a failure): then only the aliases are accepted.
+ */
+export async function liveModels(ctx, values, app) {
+    const model = typeof values.model === 'string' ? values.model.trim().toLowerCase() : '';
+    if (!model || MODEL_CHOICES[app].models.some(m => m.id === model))
+        return null;
+    // Another provider's model is refused without a request: Claude ids are claude-…; a Codex id is anything else.
+    const claudeId = model.startsWith('claude-') || MODEL_CHOICES.claude.models.some(m => m.id === model);
+    if (claudeId !== (app === 'claude'))
+        return null;
+    try {
+        const active = (await ctx.cloud().agentAccounts.allModels({ provider: app })).accounts.find(a => a.active);
+        return active ? active.models.filter(m => m.available).map(m => ({ id: m.id, efforts: m.efforts })) : null;
+    }
+    catch {
+        return null;
+    }
+}
 const list = (ids) => ids.length > 1 ? `${ids.slice(0, -1).join(', ')} or ${ids.at(-1)}` : ids[0];
 const label = (app) => app === 'claude' ? 'Claude' : 'Codex';
 /** `--model` and `--effort` for this app, checked against its list. Throws a usage error for anything else. */
-export function modelChoice(values, app) {
+export function modelChoice(values, app, live = null) {
     const raw = (name) => {
         const value = values[name];
         if (value === undefined)
@@ -39,9 +60,11 @@ export function modelChoice(values, app) {
     };
     const model = raw('model'), effort = raw('effort'), choices = MODEL_CHOICES[app];
     const option = model === undefined ? undefined : choices.models.find(m => m.id === model);
-    if (model !== undefined && !option)
-        throw new UsageError(`${label(app)} models: ${list(choices.models.map(m => m.id))}.`);
-    const allowed = option?.efforts ?? choices.efforts.map(e => e.id);
+    const listed = model === undefined || option ? undefined : live?.find(m => m.id === model);
+    if (model !== undefined && !option && !listed) {
+        throw new UsageError(`${label(app)} models: ${list(choices.models.map(m => m.id))}${live?.length ? `, or one this account has: ${live.map(m => m.id).join(', ')}` : ', or a model id from shard agents models'}.`);
+    }
+    const allowed = option?.efforts ?? (listed ? [DEFAULT_CHOICE, ...listed.efforts] : choices.efforts.map(e => e.id));
     if (effort !== undefined && !allowed.includes(effort)) {
         throw new UsageError(`${option?.efforts ? option.label : label(app)} effort levels: ${list(allowed)}.`);
     }

package/dist/agent-setup.d.ts

@@ -1,10 +1,10 @@
+import type { Ctx } from './commands.js';
 /**
  * Set in a coding agent's shell: Claude Code (CLAUDECODE), Codex (CODEX_SANDBOX, CODEX_THREAD_ID), Cursor's agent
  * (CURSOR_AGENT) and Gemini CLI (GEMINI_CLI). Such a shell may have a terminal (Cursor and Codex can run commands in a
  * PTY), but nobody types into it: a full-screen view or a prompt there waits forever.
  */
-export declare const AGENT_SHELL_VARIABLES: readonly ["CLAUDECODE", "CODEX_SANDBOX", "CODEX_THREAD_ID", "CURSOR_AGENT", "GEMINI_CLI"];
-export declare function codingAgentShell(env: Record<string, string | undefined>): boolean;
+export { AGENT_SHELL_VARIABLES, codingAgentShell } from './agent-shell.js';
 /**
  * How the agent runs the setup (0.20.1+): it does the work, the person only decides. Onboarding testers (2026-10-12)
  * found agents handing them commands, links and codes, writing paragraphs and asking open questions.
@@ -46,4 +46,6 @@ export interface GuideState {
     apiKey: boolean;
 }
 export declare function setupGuide(state: GuideState): SetupGuide;
+/** The setup guide for this computer: whether a session and an API key are saved (no network call). */
+export declare function agentSetupGuide(ctx: Ctx): ReturnType<typeof setupGuide>;
 export declare function setupGuideText(g: SetupGuide): string;

package/dist/agent-setup.js

@@ -18,10 +18,7 @@ import { legalFields } from "./legal.js";
  * (CURSOR_AGENT) and Gemini CLI (GEMINI_CLI). Such a shell may have a terminal (Cursor and Codex can run commands in a
  * PTY), but nobody types into it: a full-screen view or a prompt there waits forever.
  */
-export const AGENT_SHELL_VARIABLES = ['CLAUDECODE', 'CODEX_SANDBOX', 'CODEX_THREAD_ID', 'CURSOR_AGENT', 'GEMINI_CLI'];
-export function codingAgentShell(env) {
-    return AGENT_SHELL_VARIABLES.some((name) => (env[name]?.trim() ?? '') !== '');
-}
+export { AGENT_SHELL_VARIABLES, codingAgentShell } from "./agent-shell.js";
 /**
  * How the agent runs the setup (0.20.1+): it does the work, the person only decides. Onboarding testers (2026-10-12)
  * found agents handing them commands, links and codes, writing paragraphs and asking open questions.
@@ -137,6 +134,11 @@ function stepText(n, s) {
         ...(s.note ? [`     ${wrap(s.note, '     ', 96)}`] : []),
     ].join('\n');
 }
+/** The setup guide for this computer: whether a session and an API key are saved (no network call). */
+export function agentSetupGuide(ctx) {
+    const profile = ctx.store.profile(ctx.apiUrl);
+    return setupGuide({ signedIn: ctx.sessionSource() !== null, email: profile.session?.user?.email ?? null, apiKey: profile.api_key !== undefined || Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) });
+}
 export function setupGuideText(g) {
     return [
         'Set up Shardflux for your user. How:',

package/dist/agent-shell.d.ts

@@ -0,0 +1,2 @@
+export declare const AGENT_SHELL_VARIABLES: readonly ["CLAUDECODE", "CODEX_SANDBOX", "CODEX_THREAD_ID", "CURSOR_AGENT", "GEMINI_CLI"];
+export declare function codingAgentShell(env: Record<string, string | undefined>): boolean;

package/dist/agent-shell.js

@@ -0,0 +1,5 @@
+// Identify an agent shell before loading onboarding or command handlers.
+export const AGENT_SHELL_VARIABLES = ['CLAUDECODE', 'CODEX_SANDBOX', 'CODEX_THREAD_ID', 'CURSOR_AGENT', 'GEMINI_CLI'];
+export function codingAgentShell(env) {
+    return AGENT_SHELL_VARIABLES.some((name) => (env[name]?.trim() ?? '') !== '');
+}

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.25.0";
+export declare const CLI_VERSION = "0.28.1";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -12,9 +12,10 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { BOARD_COMMANDS } from "./board-args.js";
+import { ORCHESTRATOR_COMMANDS } from "./orchestrator-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.25.0';
+export const CLI_VERSION = '0.28.1';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -165,11 +166,12 @@ const KEY_COMMANDS = [
     { path: ['conversations', 'watch'], summary: 'Watch a conversation’s terminal live, read-only', positionals: [{ name: 'id', required: true }], options: {},
         description: 'Shows the terminal the conversation’s agent runs in (its pty_id, terminal conversations) as the agent works: its last 256 KiB, then live output, until the agent’s session exits or you press Ctrl-C. Nothing you type reaches it. Watching never keeps the computer awake while the agent is idle, and ends when the computer sleeps. The output is the terminal’s own bytes, so there is no --json form; shard agents logs <id> --json returns recent output as JSON.',
         examples: ['shard conversations watch conv_a7k2m4q6s3t5v7x2z4b6d3f5h7'] },
-    { path: ['conversations', 'send'], summary: 'Send the next user turn', positionals: [{ name: 'id', required: true }, { name: 'text', variadic: true, words: true }], options: {
-            file: { type: 'string', multiple: true, value: '<path>', description: 'Attach a file (repeatable, up to 20 of 64 MiB each): it lands in the conversation’s computer before the message, which lists its path there (0.25.0+).' }
+    { path: ['conversations', 'send'], summary: 'Send a message to a conversation’s agent', positionals: [{ name: 'id', required: true }, { name: 'text', variadic: true, words: true }], options: {
+            file: { type: 'string', multiple: true, value: '<path>', description: 'Attach a file (repeatable, up to 20 of 64 MiB each): it lands in the conversation’s computer before the message, which lists its path there (0.25.0+).' },
+            wait: { type: 'boolean', description: 'Wait up to 60 s for the agent to have the message and print what happened to it (0.27.0+).' }
         },
-        description: 'Text and files reach the conversation’s agent as its next turn. A conversation that ended is restored into a fresh computer first. Attached files keep their names under /home/user/.shardflux/attachments/<conversation id>/; each stored path is printed.',
-        examples: ['shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Fix the failing export test"', 'shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Why does this page break?" --file screenshot.png --file console.log'] },
+        description: 'A working agent takes the message into its running turn; an idle one starts its next turn with it. --wait (0.27.0+) waits up to 60 s and prints which: "Steered into the running turn.", "Started the next turn." or "Not delivered yet."; --json adds the delivery (state, delivered_at, steered). A conversation that ended is restored into a fresh computer first. Attached files keep their names under /home/user/.shardflux/attachments/<conversation id>/; each stored path is printed.',
+        examples: ['shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Fix the failing export test"', 'shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Use the staging database instead" --wait', 'shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Why does this page break?" --file screenshot.png --file console.log'] },
     { path: ['conversations', 'wait'], summary: 'Wait for a result or question', positionals: [{ name: 'id', required: true }], options: {
             until: { type: 'string', value: '<states>', description: 'Comma-separated conversation states.' }, timeout: { type: 'string', value: '<seconds>', description: 'Wait for 0..900 seconds (default 900).' }
         } },
@@ -201,6 +203,15 @@ const KEY_COMMANDS = [
         description: 'merge (0.25.0+) merges the conversation’s branch into the project’s default branch on the project hub (a fast-forward, or a merge commit when it is clean), brings it into your folder on this computer the way finished conversations land (your uncommitted edits stay), checks the commit is in the branch, and only then records it. pr, keep and discard record what was decided.',
         examples: ['shard conversations land conv_k3m5q7s2u4w6y3b5d7f2h4j6ln merge', 'shard conversations land conv_k3m5q7s2u4w6y3b5d7f2h4j6ln discard'] },
     { path: ['conversations', 'move'], summary: 'Move at the end of the turn', positionals: [{ name: 'id', required: true }, { name: 'to', required: true }], options: {} },
+    { path: ['conversations', 'archive'], summary: 'Archive conversations from your inbox, on every device (0.28.0+)', positionals: [{ name: 'id', required: true, variadic: true, words: true }], options: {},
+        description: 'Archives them from your own inbox, the same in the Shardflux app, the CLI and every client you use: each one carries your dismissed_at until you unarchive it. The conversations, their agents and computers carry on, and everyone else keeps their own inbox. Name up to 200 ids at once. Prints "Archived <id>  <title>" for each, and "Not found: <id>" on stderr for an id you cannot read (exit 3 when none was found). --json prints {data, skipped}: the conversations with your seen_at and dismissed_at, and the ids not found.',
+        examples: ['shard c archive conv_k3m5q7s2u4w6y3b5d7f2h4j6ln', 'shard conversations archive conv_k3m5q7s2u4w6y3b5d7f2h4j6ln conv_a7k2m4q6s3t5v7x2z4b6d3f5h7 --json'] },
+    { path: ['conversations', 'unarchive'], summary: 'Bring archived conversations back to your inbox, on every device (0.28.0+)', positionals: [{ name: 'id', required: true, variadic: true, words: true }], options: {},
+        description: 'Brings them back to your own inbox everywhere: their dismissed_at reads null again. Name up to 200 ids at once. Prints "Unarchived <id>  <title>" for each, and "Not found: <id>" on stderr for an id you cannot read (exit 3 when none was found). --json prints {data, skipped}.',
+        examples: ['shard c unarchive conv_k3m5q7s2u4w6y3b5d7f2h4j6ln'] },
+    { path: ['conversations', 'seen'], summary: 'Mark conversations seen: you opened them now, on every device (0.28.0+)', positionals: [{ name: 'id', required: true, variadic: true, words: true }], options: {},
+        description: 'Records that you opened them now, the same on every device: their seen_at becomes now, so a result that finished before then is no longer new to you anywhere. Name up to 200 ids at once. Prints "Marked seen <id>  <title>" for each, and "Not found: <id>" on stderr for an id you cannot read (exit 3 when none was found). --json prints {data, skipped}.',
+        examples: ['shard c seen conv_k3m5q7s2u4w6y3b5d7f2h4j6ln conv_a7k2m4q6s3t5v7x2z4b6d3f5h7'] },
     { path: ['conversations', 'delete'], summary: 'Delete a conversation everywhere: its computer, messages, transcript and branch (0.25.0+)', positionals: [{ name: 'id', required: true }], options: {
             yes: { type: 'boolean', description: 'Required: confirm the deletion.' }
         },
@@ -877,6 +888,12 @@ const KEY_COMMANDS = [
         description: `--ask (0.20.1+) asks your user for a secret file’s contents on a page on this computer; the page says Saved once the file is written. ${ASK_EVENTS}`,
         examples: ['shard files write acme/demo /home/user/notes.txt --from notes.txt', 'printf "x = 1\\n" | shard files write acme/agent-7 /home/user/app/config.py --if-revision 4', 'shard files write "$(shard machine open)" /home/user/.npmrc --ask --json'],
     },
+    {
+        path: ['files', 'delete'],
+        summary: 'Delete a file or empty directory in a workspace',
+        positionals: [REF, { name: 'path', required: true }],
+        options: { recursive: { type: 'boolean', description: 'Delete a directory and its contents (default false).' }, ...IF_REVISION, ...WAKE_TIMING },
+    },
     {
         path: ['files', 'ls'],
         summary: 'List a directory in a workspace',
@@ -1278,6 +1295,17 @@ const AGENT_ACCOUNT_COMMANDS = [
         examples: ['shard agents accounts use claude:2', 'shard agents accounts use marc@example.com --json'] },
     { path: ['agents', 'accounts', 'remove'], summary: 'Remove an account and its login (0.18.0+)', positionals: [{ name: 'account', required: true }], options: {} },
 ];
+/** The models each account can use (0.27.0+); not aliased under `shard models` (the model template). */
+const AGENT_MODELS_COMMANDS = [
+    { path: ['agents', 'models'], summary: 'The models each account can use, as Claude and ChatGPT list them for it: efforts, default, what the plan does not include (0.27.0+)', positionals: [], options: {
+            account: { type: 'string', value: '<account>', description: 'This account’s models (its id, claude:<n>, codex:<n>, email or label) instead of the active accounts’.' },
+            provider: ACCOUNT_PROVIDER,
+            all: { type: 'boolean', description: 'Every account, not only the active one of each provider.' },
+            refresh: { type: 'boolean', description: 'Ask the provider again (lists are kept for an hour).' },
+        },
+        description: 'Asked server side with each account’s own sign-in, the way Claude Code and Codex fill their model pickers; never starts a computer. Pass an id to shard agents new --model. --json prints {accounts: [...]} (one account with --account).',
+        examples: ['shard agents models', 'shard agents models --account claude:2', 'shard agents models --provider codex --json'] },
+];
 /** `shard accounts …`: the same commands, as the menu bar and the design name them. */
 const ACCOUNT_ALIASES = AGENT_ACCOUNT_COMMANDS.map(c => ({ ...c, path: c.path.slice(1), hidden: true }));
 const COMPUTER_OPTION = { type: 'boolean', description: 'Give the new conversation a desktop with a browser its agent drives (computer use).' };
@@ -1344,11 +1372,14 @@ const AGENT_COMMANDS = [
             detach: { type: 'boolean', description: 'Start it in the cloud without opening it here.' },
         }, examples: ['shard move --last', 'shard move --list', 'shard move --session 3d085e35-aa66-4866-9a53-f09719d6767c --detach --json'] },
     { path: ['device', 'requests'], summary: 'Review local device requests waiting for approval', positionals: [], options: {} },
+    { path: ['device', 'approvals'], summary: 'How this computer answers your agents: auto (allow everything), read (allow reading, ask before changes) or ask (0.27.0+)',
+        description: 'Without a mode: the current one and what ran without asking. Only your own agents run without asking; a teammate\'s request always asks.',
+        positionals: [{ name: 'mode', required: false }], options: {}, examples: ['shard device approvals auto', 'shard device approvals ask'] },
     ...['approve', 'deny'].map((action) => ({ path: ['device', action], summary: `${action} a local device request`, positionals: [{ name: 'id', required: true }], options: action === 'approve' ? { always: { type: 'boolean', description: 'Allow matching requests for this project, or for a folder request (0.25.0+) that folder and what is inside it; never for other access outside the conversation folder.' } } : {} })),
     { path: ['conversations', 'start'], summary: 'Start a conversation from the project or on your machine, no folder needed (0.25.0+)', positionals: [], options: {
             project: { type: 'string', value: '<id>', description: 'The project (default: the API key’s, or this computer’s selected project).' },
             home: { type: 'boolean', description: 'Start on your machine’s home, without a repository: the agent runs in /home/user and starts threads in the project’s repositories.' },
-            repo: { type: 'string', value: '<remote>', description: 'The repository (default: the project’s most recently active one).' },
+            repo: { type: 'string', value: '<remote>', description: 'The repository (default: the project’s only one; a project with several asks you to name it).' },
             branch: { type: 'string', value: '<name>', description: 'Start from this branch’s newest saved point in the project (default main, then master).' },
             app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default claude).' },
             title: { type: 'string', value: '<text>', description: 'The conversation’s title (default: named by its first message).' },
@@ -1430,9 +1461,10 @@ const MENUBAR_COMMANDS = [{ path: ['menubar', 'account'], hidden: true, summary:
 const SETTINGS_COMMANDS = [{
         path: ['settings'], summary: 'Show or change this computer’s settings for cloud conversations (0.20.1+)', positionals: [], options: {
             'title-prefix': { type: 'string', value: '<text|none|default>', description: 'The marker your cloud conversations’ Claude session titles start with in claude.ai and the Claude app ("☁ Fix login bug · todo-app"): up to 16 characters on one line; none for no marker, default for ☁. New conversations use it.' },
+            'auto-land': { type: 'string', value: '<on|off>', description: 'Bring finished cloud work (conversations and board tasks) into your folders on this computer automatically (0.27.0+, default on).' },
         },
-        description: 'Shows the title marker, where new conversations open and the terminal app (change those two with "shard agents targets --open-in" and "--terminal"). The menu bar and desktop apps change the same settings.',
-        examples: ['shard settings', 'shard settings --title-prefix SF', 'shard settings --title-prefix none', 'shard settings --title-prefix default --json'],
+        description: 'Shows the title marker, where new conversations open, the terminal app (change those two with "shard agents targets --open-in" and "--terminal") and auto land. The menu bar and desktop apps change the same settings.',
+        examples: ['shard settings', 'shard settings --title-prefix SF', 'shard settings --title-prefix none', 'shard settings --title-prefix default --json', 'shard settings --auto-land off'],
     }];
 /** The board's input bar from a terminal (0.25.0+): route a line of input, ask a quick question about the work. */
 const BOARD_SCOPE = {
@@ -1443,8 +1475,9 @@ const BOARD_SCOPE_HELP = 'Reads your organization’s projects and open tasks wi
 const ROUTER_COMMANDS = [
     {
         path: ['route'],
-        summary: 'Route input like the board’s input bar: its project, task, question or steer, split per task (0.25.0+)',
+        summary: 'Deprecated: route input like the board’s input bar (use shard orchestrator say) (0.25.0+)',
         description: [
+            'Deprecated: shard orchestrator say <words> sends your input to your orchestrator, which routes it, answers it or files its tasks.',
             'Decides which project the input belongs to (or your home, for personal work), whether it is a new task, a question or a steer for an open task, and splits input that asks for several tasks into your own words per task, each with a title. "?" or "quick question" at the start makes it a question.',
             BOARD_SCOPE_HELP,
             'Prints the kind and where it goes, then each part. With --json: the RouterResult (kind, parts with text, title, project_id and home, task_ref, confidence, uncertain, forced, routed_by, latency_ms).',
@@ -1458,8 +1491,9 @@ const ROUTER_COMMANDS = [
     },
     {
         path: ['ask'],
-        summary: 'Ask a quick question about your work, answered from the board as it is written (0.25.0+)',
+        summary: 'Deprecated: ask a quick question about your work (use shard orchestrator say) (0.25.0+)',
         description: [
+            'Deprecated: shard orchestrator say --wait <question> asks your orchestrator and prints its answer.',
             'Answers from your tasks, their plans and states, sealed reports, the conversations behind them and what their agents last wrote. The answer streams to standard output as it is written; one that needs work ends with "Make it a task?".',
             BOARD_SCOPE_HELP,
             'With --json: the whole answer as one object (text, needs_work, sources, answered_by, first_token_ms, total_ms).',
@@ -1518,6 +1552,26 @@ const DRIVE_COMMANDS = [
         description: `${DRIVE_HELP} After rm the path no longer lists or reads; shard drive get <path> --sha256 <hex> still reads each of its versions.`,
         examples: ['shard drive rm tasks/t_ab12/notes/draft.md'] },
 ];
+/** Whose brain a brain command reads (0.27.0+): the person's in this organization. */
+const BRAIN_SCOPE = {
+    org: { type: 'string', value: '<id|slug>', description: 'Organization whose brain it is (default: the saved one, shard orgs use, else your only organization). Slugs need your signed-in session.' },
+};
+const BRAIN_HELP = 'Your brain is your archive in an organization, kept by your orchestrator: every answer it publishes is filed as reports/<YYYY-MM-DD>/<folder>/report.md with the answer’s media next to it (image thumbnails under .thumbs/), with its own notes and files and an index.md of everything, newest first. Your orchestrator writes it; you read it from any device, with every computer asleep. Paths are relative to the brain’s root, the names ~/brain shows on your orchestrator’s computer. Uses your signed-in session, or SHARDFLUX_API_KEY when it is set (a key reads the brain of the member who created it).';
+const BRAIN_COMMANDS = [
+    { path: ['brain', 'ls'], summary: 'List your brain’s files: size, saved time, type and path (0.27.0+)', positionals: [{ name: 'prefix' }], options: {
+            ...BRAIN_SCOPE,
+            all: { type: 'boolean', description: 'Fetch every page.' },
+            limit: { type: 'string', value: '<n>', description: 'Page size (1 to 1000, default 200).' },
+            cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
+        }, description: `${BRAIN_HELP} Lists the current version of each file, by path; a prefix such as reports/2026-10-17/ lists only that folder. --json returns data (each file with its sha256), next_cursor and the brain’s version, which moves whenever anything in it changes.`,
+        examples: ['shard brain ls', 'shard brain ls reports/2026-10-17/', 'shard brain ls --all --json'] },
+    { path: ['brain', 'get'], summary: 'Read a file from your brain: its bytes to standard output, or to a file with -o (0.27.0+)', positionals: [{ name: 'path', required: true }], options: {
+            ...BRAIN_SCOPE,
+            sha256: { type: 'string', value: '<hex>', description: 'Read exactly this version (the current one or an earlier one).' },
+            out: { type: 'string', short: 'o', value: '<file>', description: 'Write the bytes to this file.' },
+        }, description: `${BRAIN_HELP} The bytes are checked against their SHA-256 before they are written. --json without -o returns the file as content_base64 with its sha256, size and content_type.`,
+        examples: ['shard brain get index.md', 'shard brain get reports/2026-10-17/training-progress-ab12cd34/report.md', 'shard brain get reports/2026-10-17/training-progress-ab12cd34/loss.png -o loss.png'] },
+];
 const MODELS_HELP = 'The model template: which agent app (harness), model and effort each role of a task runs with, from the Claude and Codex accounts your organization connected. master plans and coordinates, builder does the work, hard takes the hardest parts, light the small ones, and reviewer reviews with a fresh context. The primary provider runs master, builder and hard; the other one, light and reviewer. A role whose account waits for its next usage window shows until when, and what the other provider would run now.';
 const MODEL_COMMANDS = [
     { path: ['models'], summary: 'Show which harness, model and effort each role of a task runs with (0.25.0+)', positionals: [], options: {
@@ -1532,7 +1586,7 @@ const MODEL_COMMANDS = [
         }, description: `${MODELS_HELP} The primary is this project’s choice when it has one, else the organization’s, else the provider connected first; clear removes the choice. Prints the template with the new primary.`,
         examples: ['shard models primary codex', 'shard models primary claude --org acme', 'shard models primary clear --project web'] },
 ];
-export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...ROUTER_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...AGENT_ACCOUNT_COMMANDS, ...ACCOUNT_ALIASES, ...CLI_PROXY_COMMANDS, ...MENUBAR_COMMANDS, ...SETTINGS_COMMANDS, ...KEY_COMMANDS, ...BOARD_COMMANDS, ...DRIVE_COMMANDS, ...MODEL_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
+export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...ROUTER_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...AGENT_ACCOUNT_COMMANDS, ...AGENT_MODELS_COMMANDS, ...ACCOUNT_ALIASES, ...CLI_PROXY_COMMANDS, ...MENUBAR_COMMANDS, ...SETTINGS_COMMANDS, ...KEY_COMMANDS, ...ORCHESTRATOR_COMMANDS, ...BOARD_COMMANDS, ...DRIVE_COMMANDS, ...BRAIN_COMMANDS, ...MODEL_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
 const GROUPS = {
     device: 'Local device approvals',
     'cli-proxy': 'Your hosted CLIProxyAPI, reachable at http://127.0.0.1:8317 on this computer and in every VM',
@@ -1542,6 +1596,7 @@ const GROUPS = {
     'needs-you': 'Everything your agents wait on, oldest first, and one answer command for each (0.25.0+)',
     approvals: 'The approval mode and always-allow rules your agents work under (0.25.0+)',
     drive: 'The project drive: files every agent, phone and person of the project reads and writes, each version kept by its SHA-256 (0.25.0+)',
+    brain: 'Your brain: your orchestrator’s answers, reports and notes, read from any device (0.27.0+)',
     models: 'The model template: which harness, model and effort each role of a task runs with, and the primary provider (0.25.0+)',
     agents: 'Cloud agent sessions and copied credentials',
     auth: 'Create an account and sign in (the session is saved in the credentials file); passwords, email, two-factor authentication and sessions',
@@ -1955,7 +2010,7 @@ export const EXIT_CODE_HELP = [
 /** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
 export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
-    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'board', 'task', 'needs-you', 'approvals', 'route', 'ask', 'transcribe', 'drive', 'models', 'move', 'machine', 'template', 'agents', 'settings', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
+    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'orchestrator', 'brain', 'board', 'task', 'needs-you', 'approvals', 'route', 'ask', 'transcribe', 'drive', 'models', 'move', 'machine', 'template', 'agents', 'settings', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
     { title: 'Workspaces for your app (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
     { title: 'Templates for your app’s workspaces (not for cloud agents; publish and archive use the session, the rest the API key)', groups: ['templates'] },
     { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },

package/dist/board-args.js

@@ -109,9 +109,11 @@ export const BOARD_COMMANDS = [
         positionals: [],
         options: PROJECT_FILTER,
         description: [
-            'Everything your agents wait on, across the board: permission requests (perm_…), questions (cq_…, ask_…),',
-            'credential requests (cred_…), finished work to land (land_…) and Later tasks to keep or clear (prune_…). Each line is',
-            'the id, what is asked, and the command, options or branch behind it. Answer with shard needs-you answer <id>.',
+            'Everything your agents wait on, across the board: permission requests (perm_…), questions (cq_…, ask_…, and your',
+            'orchestrator’s oq_…), credential requests (cred_…), finished work to land (land_…), Later tasks to keep or clear',
+            '(prune_…) and what your orchestrator asked your computer while it was offline (dev_…, "Waiting for your computer:',
+            'list ~/code"). Each line is the id, what is asked, and the command, options or branch behind it. Answer with shard',
+            'needs-you answer <id>.',
             '--json returns {data}.',
         ].join('\n'),
         examples: ['shard needs-you', 'shard needs-you --json'],
@@ -132,10 +134,13 @@ export const BOARD_COMMANDS = [
             '            project) or deny; an agent’s question takes --pick',
             '  cq_…      --text <answer>: the agent gets it as its next message',
             '  ask_…     --text <answer>: the task’s master gets it',
+            '  oq_…      --text <answer>: the orchestrator thread that asked gets it (0.27.0+)',
             '  cred_…    deny (the value goes through the credential request, sealed for its computer)',
             '  land_…    land (as shard task land: the result into your folder and the default branch), keep (the',
             '            branch stays) or discard',
             '  prune_…   --keep <task-id> for each task to keep, keep for all of them, or discard to clear them',
+            '  dev_…     cancel: drops what your orchestrator asked your computer (it runs by itself when your computer is',
+            '            back) (0.27.0+)',
             'The agent goes on as soon as you answer.',
         ].join('\n'),
         examples: ['shard needs-you answer perm_01a1300c-0000-7000-8000-000000000001 always', 'shard needs-you answer ask_rep_66cbevz65m72ij7mbiyrw4xvdy --text "eu-north-1"', 'shard needs-you answer land_conv_id4zts6jxsqraju2pggr55n3tq land'],

package/dist/board-commands.d.ts

@@ -14,7 +14,10 @@ export declare function taskLabel(t: Pick<Task, 'title' | 'text'>, max?: number)
  * what it does now, "working (Fixing the login cookie)"), title or words (a follow-up ↳, a suggestion marked), project.
  */
 export declare function taskLine(t: Task): string;
-/** One item that waits on you: its id, what is asked, then the command, the suggested answers or the branch behind it. */
+/**
+ * One item that waits on you: its id, what is asked, then the command, the suggested answers or the branch behind it. A
+ * request your orchestrator made to your computer while it was offline reads "Waiting for your computer: list ~/code".
+ */
 export declare function needsLine(n: NeedsYouItem): string;
 /** A sealed report as --follow prints it: id, milestone, title, then its evidence labels. */
 export declare function reportLine(r: TaskReport): string;
@@ -38,9 +41,10 @@ export declare class BoardFollower {
 }
 /** A feed answer as `board --follow --json` prints it: the API's fields (with `board` after a reset). */
 export declare function feedJson(u: BoardUpdate): Record<string, unknown>;
-/** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. */
+/** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. Every
+ *  title, step and outcome prints whole (0.27.0+), however long the agent wrote it; the terminal wraps it. */
 export declare function taskDetailText(d: TaskDetail): string;
-/** An item's kind from its id (perm_, cq_, ask_, cred_, land_, prune_); undefined for another id. */
+/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, land_, prune_, dev_); undefined for another id. */
 export declare function itemKind(id: string): NeedsYouItem['kind'] | undefined;
 export interface AnswerInput {
     word?: string | undefined;

package/dist/board-commands.js

@@ -31,9 +31,12 @@ export function taskLine(t) {
     const label = `${t.parent_task_id ? '↳ ' : ''}${taskLabel(t)}${t.suggested ? ' (suggested)' : ''}`;
     return `${t.id}\t${state}\t${label}\t${t.project_id}${t.home ? ' (home)' : ''}`;
 }
-/** One item that waits on you: its id, what is asked, then the command, the suggested answers or the branch behind it. */
+/**
+ * One item that waits on you: its id, what is asked, then the command, the suggested answers or the branch behind it. A
+ * request your orchestrator made to your computer while it was offline reads "Waiting for your computer: list ~/code".
+ */
 export function needsLine(n) {
-    const detail = n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.join(' / ') : n.land ? n.land.branch : '';
+    const detail = n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.join(' / ') : n.land ? n.land.branch : n.device ? 'cancel drops it' : '';
     return `${n.id}\t${oneLine(n.ask, 100)}${detail ? `\t${detail}` : ''}`;
 }
 /** A sealed report as --follow prints it: id, milestone, title, then its evidence labels. */
@@ -112,11 +115,13 @@ const evidenceText = (e) => {
     const behind = e.detail ?? e.path;
     return behind ? `${e.label} (${detailLine(behind, 60)})` : e.label;
 };
-/** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. */
+/** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. Every
+ *  title, step and outcome prints whole (0.27.0+), however long the agent wrote it; the terminal wraps it. */
 export function taskDetailText(d) {
     const t = d.task;
+    const whole = (s) => oneLine(s, Infinity);
     const titled = Boolean(t.title?.trim());
-    const lines = [titled ? oneLine(t.title, 200) : oneLine(t.text.split('\n').find((l) => l.trim()) ?? t.text, 200)];
+    const lines = [titled ? whole(t.title) : whole(t.text.split('\n').find((l) => l.trim()) ?? t.text)];
     lines.push([`${t.state}${stateNote(t, 120)}`, t.bucket, `${t.project_id}${t.home ? ' (home)' : ''}`, ...(t.suggested ? ['suggested'] : []), ...(t.deleted_at ? ['deleted'] : t.cleared_at ? ['cleared'] : [])].join('\t'));
     // Your words exactly, when the first line does not already show them whole.
     if (titled || t.text.trim() !== lines[0])
@@ -124,16 +129,16 @@ export function taskDetailText(d) {
     if (t.plan) {
         lines.push('', `Plan: ${t.plan.summary}`);
         for (const s of t.plan.steps)
-            lines.push(`  ${s.id}\t${s.state}\t${oneLine(s.text, 100)}${s.now?.trim() ? `\t(${oneLine(s.now, 80)})` : ''}${s.evidence.length ? `\t${s.evidence.join(', ')}` : ''}`);
+            lines.push(`  ${s.id}\t${s.state}\t${whole(s.text)}${s.now?.trim() ? `\t(${oneLine(s.now, 80)})` : ''}${s.evidence.length ? `\t${s.evidence.join(', ')}` : ''}`);
     }
     if (t.conversations.length)
         lines.push('', `Conversations: ${t.conversations.map((c) => `${c.id} (${c.role}${c.step_id ? ` ${c.step_id}` : ''})`).join(', ')}`);
     if (d.reports.length) {
         lines.push('', 'Reports');
         for (const r of d.reports) {
-            lines.push(`${r.id}\t${r.milestone}\t${time(r.sealed_at)}\t${oneLine(r.title, 120)}`);
+            lines.push(`${r.id}\t${r.milestone}\t${time(r.sealed_at)}\t${whole(r.title)}`);
             if (r.outcome.trim())
-                lines.push(`  ${oneLine(r.outcome, 200)}`);
+                lines.push(`  ${whole(r.outcome)}`);
             if (r.options?.length)
                 lines.push(`  Options: ${r.options.join(' / ')}`);
             if (r.evidence.length)
@@ -161,13 +166,13 @@ function orderOf(values) {
     return first ? null : after;
 }
 // ---- needs you -------------------------------------------------------------------------------
-const KINDS = { perm: 'permission', cq: 'question', ask: 'question', cred: 'credential', land: 'land', prune: 'prune' };
-/** An item's kind from its id (perm_, cq_, ask_, cred_, land_, prune_); undefined for another id. */
+const KINDS = { perm: 'permission', cq: 'question', ask: 'question', oq: 'question', cred: 'credential', land: 'land', prune: 'prune', dev: 'device' };
+/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, land_, prune_, dev_); undefined for another id. */
 export function itemKind(id) {
     return KINDS[id.slice(0, Math.max(0, id.indexOf('_')))];
 }
-/** The answer words: allow, always and deny (or the API's names), land, keep and discard. */
-const WORDS = { allow: 'allow_once', allow_once: 'allow_once', always: 'allow_always', allow_always: 'allow_always', deny: 'deny', land: 'land', keep: 'keep', discard: 'discard' };
+/** The answer words: allow, always and deny (or the API's names), land, keep, discard and cancel. */
+const WORDS = { allow: 'allow_once', allow_once: 'allow_once', always: 'allow_always', allow_always: 'allow_always', deny: 'deny', land: 'land', keep: 'keep', discard: 'discard', cancel: 'cancel' };
 /** Whether the answer needs the item itself: the questions of a permission request, every task of a prune prompt. */
 export const answerNeedsItem = (id, a) => a.picks.length > 0 || (itemKind(id) === 'prune' && a.word?.toLowerCase() === 'keep');
 /**
@@ -214,6 +219,11 @@ export function needsAnswer(id, a, item) {
             if (decision !== 'deny')
                 throw new UsageError('Provide the value through the credential request, sealed for its computer; deny declines it here.');
             return { decision };
+        case 'device':
+            only([], 'It runs when your computer is back (the Shardflux app open); cancel drops it.');
+            if (decision !== 'cancel')
+                throw new UsageError('It runs when your computer is back (the Shardflux app open); cancel drops it.');
+            return { decision };
         case 'land':
             only([], 'Choose land, keep or discard.');
             if (decision !== 'land' && decision !== 'keep' && decision !== 'discard')
@@ -248,7 +258,7 @@ export function needsAnswer(id, a, item) {
         }
     }
 }
-const ANSWERED = { allow_once: 'Allowed once', allow_always: 'Always allowed', deny: 'Denied', land: 'Landing', keep: 'Kept', discard: 'Discarded' };
+const ANSWERED = { allow_once: 'Allowed once', allow_always: 'Always allowed', deny: 'Denied', land: 'Landing', keep: 'Kept', discard: 'Discarded', cancel: 'Canceled' };
 /** What an answer did, in one line. */
 export function answeredText(r, a) {
     const item = r.item;

package/dist/brain-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from './commands.js';
+export declare const BRAIN_HANDLERS: Record<string, Handler>;