@shardflux/cli 0.28.2 → 0.28.3

package/dist/handler-loader.js

@@ -9,7 +9,7 @@ const groups = [
     [["cli-proxy", "cli-proxy import", "cli-proxy export", "cli-proxy use", "cli-proxy forward"], async () => (await import("./cli-proxy.js")).CLI_PROXY_HANDLERS],
     [["agents computers"], async () => (await import("./thread-on-computer.js")).THREAD_HANDLERS],
     [["conversations resume", "conversations reader", "conversations list", "conversations feed", "conversations get", "conversations permissions", "conversations answer", "conversations watch", "conversations send", "conversations start", "conversations wait", "conversations land", "files pull", "conversations move", "conversations archive", "conversations unarchive", "conversations seen", "conversations delete"], async () => (await import("./conversation-commands.js")).CONVERSATION_HANDLERS],
-    [["orchestrator say", "orchestrator list", "orchestrator retry", "orchestrator dismiss", "orchestrator restore"], async () => (await import("./orchestrator-commands.js")).ORCHESTRATOR_HANDLERS],
+    [["orchestrator show", "orchestrator say", "orchestrator list", "orchestrator retry", "orchestrator dismiss", "orchestrator restore"], async () => (await import("./orchestrator-commands.js")).ORCHESTRATOR_HANDLERS],
     [["board", "task add", "task show", "task edit", "task rm", "task steer", "task land", "task clear-done", "needs-you", "needs-you answer", "approvals", "approvals set", "approvals allow", "approvals remove"], async () => (await import("./board-commands.js")).BOARD_HANDLERS],
     [["conversations transcript", "conversations events"], async () => (await import("./conversation-transcript.js")).TRANSCRIPT_HANDLERS],
     [["conversations try"], async () => (await import("./conversation-local.js")).CONVERSATION_HANDLERS],
@@ -25,6 +25,7 @@ const groups = [
     [["agents targets", "agents terminal-run", "agents open claude-desktop", "agents open codex-app", "agents open t3", "agents open web", "ssh-proxy"], async () => (await import("./agent-target-commands.js")).TARGET_HANDLERS],
     [["agents merge", "agents keep", "agents discard", "agents worktree", "agents restore"], async () => (await import("./agent-git-commands.js")).AGENT_GIT_HANDLERS],
     [["menubar start", "menubar stop", "menubar status", "menubar account"], async () => (await import("./menubar.js")).MENUBAR_HANDLERS],
+    [["credentials setup"], async () => (await import("./credential-setup.js")).CREDENTIAL_SETUP_HANDLERS],
     [["machine", "machine open", "machine save", "machine rollback", "template", "template save", "template rollback", "template delete"], async () => (await import("./filesystem-commands.js")).FILESYSTEM_HANDLERS],
     [["machine setup"], async () => (await import("./machine-setup.js")).MACHINE_SETUP_HANDLERS],
     [["settings"], async () => (await import("./client-settings.js")).SETTINGS_HANDLERS],

package/dist/handlers.js

@@ -30,8 +30,9 @@ import { ACCOUNT_POOL_HANDLERS, AGENT_MODELS_HANDLERS } from "./account-pool.js"
 import { MOVE_HANDLERS } from "./move.js";
 import { AGENT_CONFIG_HANDLERS } from "./agent-config-sync.js";
 import { MACHINE_SETUP_HANDLERS } from "./machine-setup.js";
+import { CREDENTIAL_SETUP_HANDLERS } from "./credential-setup.js";
 import { SETTINGS_HANDLERS } from "./client-settings.js";
 import { PROJECT_PREPARATION_HANDLERS } from "./project-preparation.js";
 import { DRIVE_HANDLERS } from "./drive-commands.js";
 import { BRAIN_HANDLERS } from "./brain-commands.js";
-export const HANDLERS = { ...PROJECT_PREPARATION_HANDLERS, ...PROJECT_LINK_HANDLERS, ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...ORCHESTRATOR_HANDLERS, ...BOARD_HANDLERS, ...TRANSCRIPT_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...AGENT_MODELS_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...MACHINE_SETUP_HANDLERS, ...SETTINGS_HANDLERS, ...UPDATE_HANDLERS, ...AGENT_CONFIG_HANDLERS, ...ROUTER_HANDLERS, ...TRANSCRIBE_HANDLERS, ...DRIVE_HANDLERS, ...BRAIN_HANDLERS };
+export const HANDLERS = { ...PROJECT_PREPARATION_HANDLERS, ...PROJECT_LINK_HANDLERS, ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...ORCHESTRATOR_HANDLERS, ...BOARD_HANDLERS, ...TRANSCRIPT_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...AGENT_MODELS_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...MACHINE_SETUP_HANDLERS, ...CREDENTIAL_SETUP_HANDLERS, ...SETTINGS_HANDLERS, ...UPDATE_HANDLERS, ...AGENT_CONFIG_HANDLERS, ...ROUTER_HANDLERS, ...TRANSCRIBE_HANDLERS, ...DRIVE_HANDLERS, ...BRAIN_HANDLERS };

package/dist/land.d.ts

@@ -4,7 +4,7 @@ import type { TwinCell } from './worktree-twin.js';
 /** The hub side of a landing, shipped next to this module (src in the monorepo, dist when published). */
 export declare function hubScript(): string;
 export interface HubLanding {
-    state: 'landed' | 'conflict' | 'unrelated' | 'missing' | 'raced' | 'error';
+    state: 'landed' | 'conflict' | 'unrelated' | 'missing' | 'unready' | 'raced' | 'error';
     into: string;
     before?: string | null;
     after?: string;
@@ -18,6 +18,7 @@ export interface HubLanding {
     source?: string;
     message?: string;
     reason?: string;
+    unintegrated?: string[];
 }
 /** Merges `result` (made from `sources` when missing) into the hub's default branch, in a VM that reads the hub. */
 export declare function landOnHub(cell: TwinCell, input: {
@@ -26,6 +27,7 @@ export declare function landOnHub(cell: TwinCell, input: {
     title: string;
     into?: string;
     hub?: string;
+    requireResult?: boolean;
 }, signal?: AbortSignal): Promise<HubLanding>;
 export interface FolderLanding {
     path: string;
@@ -114,6 +116,7 @@ export declare function landedText(o: LandOutcome): string;
 /** `shard task land <task>`: the task's result into the project's default branch and the linked folder, then recorded. */
 export declare function landTask(d: LandDeps, taskId: string, opts?: {
     path?: string;
+    automatic?: boolean;
 }): Promise<LandOutcome>;
 /** `shard conversations land <id> merge`: the conversation's branch into the default branch and its folder, then recorded. */
 export declare function landConversation(d: LandDeps, id: string, opts?: {

package/dist/land.js

@@ -24,12 +24,15 @@ import { selectedProjects } from "./project-preparation.js";
 import { projectIdentity } from "./project-identity.js";
 import { HUB_PATH, backupRoot, deviceId, git, gitText, inspectWorktree, landingRound, listWorktrees } from "./worktree-twin.js";
 import { projectHubCell } from "./worktree-twin-engine.js";
+import { createHash } from 'node:crypto';
+import { withTargetLock } from "./target-lock.js";
+import { TwinLedger } from "./worktree-twin.js";
 let script;
 /** The hub side of a landing, shipped next to this module (src in the monorepo, dist when published). */
 export function hubScript() { return script ??= readFileSync(new URL('./task-land-hub.py', import.meta.url), 'utf8'); }
 /** Merges `result` (made from `sources` when missing) into the hub's default branch, in a VM that reads the hub. */
 export async function landOnHub(cell, input, signal) {
-    const body = { hub: input.hub ?? HUB_PATH, result: input.result, sources: input.sources, title: input.title, ...(input.into ? { default: input.into } : {}) };
+    const body = { hub: input.hub ?? HUB_PATH, result: input.result, sources: input.sources, title: input.title, ...(input.into ? { default: input.into } : {}), ...(input.requireResult ? { require_result: true } : {}) };
     const r = await cell.exec.run(['python3', '-c', hubScript()], { stdin: JSON.stringify(body), timeoutMs: 300_000, maxOutputBytes: 1 << 20, ...(signal ? { signal } : {}) });
     const line = r.stdout.trim().split('\n').at(-1) ?? '';
     if (r.exitCode !== 0 || !line.startsWith('{'))
@@ -133,10 +136,14 @@ export function landDeps(ctx) {
 async function land(d, l, onConflict) {
     const vm = await d.hubCell(l.projectId, l.workspaceIds);
     try {
-        const input = { result: l.result, sources: l.sources.map(s => s.branch), title: l.title, ...(d.hub ? { hub: d.hub } : {}) };
+        const input = { result: l.result, sources: l.sources.map(s => s.branch), title: l.title, ...(d.hub ? { hub: d.hub } : {}), ...(l.testedResult ? { requireResult: true } : {}) };
         let hub = await landOnHub(vm.cell, input, d.signal);
         if (hub.state === 'raced')
             hub = await landOnHub(vm.cell, input, d.signal);
+        if (hub.state === 'unready') {
+            await onConflict(hub);
+            throw new CodedError('land_result_unready', 'The task result is waiting for its master to merge, test and push every worker branch.', undefined, { reason: hub.reason, unintegrated: hub.unintegrated });
+        }
         if (hub.state === 'conflict') {
             await onConflict(hub);
             throw new CodedError('land_conflict', `Not landed: ${list(hub.conflicts ?? [])} changed on both sides (${hub.stage === 'integrate' ? `${hub.source} and ${l.result}` : `${l.result} and ${hub.into}`}).`, 'its master merges them and asks to land again', { stage: hub.stage, into: hub.into, conflicts: hub.conflicts ?? [] });
@@ -210,9 +217,17 @@ function currentResult(d) {
 const resultBranch = (taskId) => `shard/${taskId}`;
 /** `shard task land <task>`: the task's result into the project's default branch and the linked folder, then recorded. */
 export async function landTask(d, taskId, opts = {}) {
+    // The desktop board, service and a terminal can notice the same result together. Serialize their real merge and
+    // re-read its current done report inside the lock; Git and the API still check the commit/report on every device.
+    const key = createHash('sha256').update(taskId).digest('hex');
+    return withTargetLock(join(d.stateDir, 'task-land-locks', key), () => landTaskUnlocked(d, taskId, opts), d.signal);
+}
+async function landTaskUnlocked(d, taskId, opts) {
     const client = d.client, signal = d.signal ? { signal: d.signal } : {};
     const detail = await client.tasks.get(taskId, signal);
     const task = detail.task, title = task.title ?? task.text.split('\n')[0].slice(0, 80);
+    if (opts.automatic && new TwinLedger(d.stateDir).mode(task.project_id) !== 'auto')
+        throw new CodedError('land_automatic_off', 'Automatic landing is off on this computer or for this project.');
     const report = currentResult(detail);
     if (!report || (task.state !== 'done' && task.state !== 'unverified'))
         throw new CodedError('task_not_done', 'This task has no finished result to land yet.', 'land it after its master’s done report', { state: task.state });
@@ -227,11 +242,25 @@ export async function landTask(d, taskId, opts = {}) {
     // The repository the result is of: its workers' (or its master's), so it lands only in a folder of that repository.
     const repository = workers.find(w => w.repo_remote)?.repo_remote ?? (task.master_id ? (await client.conversations.get(task.master_id).catch(() => null))?.repo_remote : undefined) ?? null;
     const folder = opts.path ?? d.folder(task.project_id, undefined, repository ?? undefined);
+    // A task created on the phone has no local conversation record. Wait for its actual linked repository; never
+    // wake a VM or mark a hub-only merge as delivery to an arbitrary folder on this computer.
+    if (opts.automatic && !folder)
+        throw new CodedError('land_device_unlinked', 'This task has no linked repository folder on this computer.');
     const done = await land(d, { projectId: task.project_id, title, name: taskId, result: resultBranch(taskId), sources: workers.map(w => ({ branch: w.branch, conversation_id: w.id })),
-        base: workers.find(w => w.base_commit)?.base_commit ?? null, folder, repository, workspaceIds: workers.map(w => w.workspace_id).filter(Boolean) }, async (hub) => {
+        base: workers.find(w => w.base_commit)?.base_commit ?? null, folder, repository, workspaceIds: workers.map(w => w.workspace_id).filter(Boolean), testedResult: opts.automatic }, async (hub) => {
+        if (hub.state === 'unready') {
+            await client.tasks.steer(taskId, `Auto land is waiting for the tested task result: ${resultBranch(taskId)} ${hub.reason === 'result_missing' ? 'has not been pushed' : `does not contain ${list(hub.unintegrated ?? [])}`}. Merge every worker branch into it, resolve conflicts, run the tests on that merged result, push it to the project hub and seal done again.`, signal);
+            return;
+        }
         const what = hub.stage === 'integrate' ? `${hub.source} into ${resultBranch(taskId)}` : `${resultBranch(taskId)} into ${hub.into}`;
         await client.tasks.steer(taskId, `Land could not merge ${what}: ${list(hub.conflicts ?? [])} changed on both sides. Merge ${hub.into} from the project hub and every worker branch into ${resultBranch(taskId)}, resolve the conflicts so both changes work (ask the person only if the choice is theirs), run the tests, push ${resultBranch(taskId)} to the hub and seal done again.`, signal);
     });
+    if (opts.automatic && done.folder?.state !== 'landed' && done.folder?.state !== 'already') {
+        const conflict = done.folder?.state === 'conflict';
+        throw new CodedError(conflict ? 'land_conflict' : 'land_folder_busy', conflict
+            ? `Not landed in your folder: ${list(done.folder?.conflicts ?? [])} changed on both sides.`
+            : 'The linked folder is busy; its finished task will land when it is ready.');
+    }
     let recorded = false, record_error;
     try {
         await client.tasks.recordLanding(taskId, { sha: done.result.sha, into: done.hub.into, branch: done.result.branch, reportId: report, conversationIds: done.contained }, signal);

package/dist/machine-setup.d.ts

@@ -173,6 +173,7 @@ export interface SetupDeps {
         state: AgentFilesystem;
         ws: Workspace;
     }>;
+    credentials?: (ctx: Ctx) => Promise<void>;
 }
 export declare function machineSetup(ctx: Ctx, values: Values, deps?: SetupDeps): Promise<number>;
 /**

package/dist/machine-setup.js

@@ -707,6 +707,8 @@ export async function machineSetup(ctx, values, deps = {}) {
     const claim = claimRun(store, ctx.apiUrl, org, values['if-needed'] === true, startRec);
     if (!claim.claimed) {
         const { doc, text } = await status();
+        if (claim.record.state === 'ready')
+            await deps.credentials?.(ctx);
         return output(ctx, { ...doc, skipped: true }, claim.record.state === 'running' ? `${text} (already running)` : text);
     }
     const phase = phaseWriter(ctx);
@@ -781,6 +783,7 @@ export async function machineSetup(ctx, values, deps = {}) {
         writeRecord(store, ctx.apiUrl, org, rec);
         phase('ready', line);
         const row = machineRow(saved, rec);
+        await deps.credentials?.(ctx);
         return output(ctx, { ...statusDoc(row, rec), workspace_key: ws.key }, rowText(row));
     }
     catch (error) {
@@ -808,7 +811,7 @@ export function startMachineSetupInBackground(ctx) {
         mkdirSync(ctx.store.dir, { recursive: true, mode: 0o700 });
         const out = openSync(join(ctx.store.dir, 'machine-setup.out'), 'w', 0o600);
         try {
-            const child = spawn(ctx.runtime.node, [ctx.runtime.script, 'machine', 'setup', '--from-this-computer', '--if-needed', '--json'], {
+            const child = spawn(ctx.runtime.node, [ctx.runtime.script, 'machine', 'setup', '--from-this-computer', '--if-needed', '--with-credentials', '--json'], {
                 detached: true, stdio: ['ignore', out, out],
                 env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, SHARDFLUX_NO_UPDATE_CHECK: '1' }
             });
@@ -825,5 +828,5 @@ export function startMachineSetupInBackground(ctx) {
     }
 }
 export const MACHINE_SETUP_HANDLERS = {
-    'machine setup': (ctx, values) => machineSetup(ctx, values),
+    'machine setup': async (ctx, values) => machineSetup(ctx, values, values['with-credentials'] === true ? { credentials: (await import("./credential-setup.js")).credentialSetupAfterMachine } : {}),
 };

package/dist/main.js

@@ -403,6 +403,24 @@ function feedbackHint(info, credentialHint) {
     }
     return `the feedback was not sent; email it to ${FEEDBACK_EMAIL} instead`;
 }
+function credentialFailure(info) {
+    const status = info.status;
+    const known = {
+        400: ['validation_failed', 'Check the credential name and scope, then try again.'],
+        401: ['unauthenticated', 'Sign in again, then retry the credential operation.'],
+        403: ['forbidden', 'This account cannot change credentials in that scope.'],
+        404: ['not_found', 'The credential or its request is no longer available.'],
+        409: ['conflict', 'The credential already exists or its request was answered. Refresh and try again.'],
+        413: ['validation_failed', 'The credential exceeds the secret store’s existing value size.'],
+        422: ['validation_failed', 'Check the credential name and scope, then try again.'],
+        429: ['rate_limited', 'The credential service is busy. Try again shortly.'],
+    };
+    const [code, message] = status === undefined ? ['credential_failed', 'The credential operation could not finish. Try again.']
+        : known[status] ?? ['dependency_unavailable', 'The credential service could not finish the operation. Try again shortly.'];
+    return { code, message, ...(status !== undefined ? { status } : {}),
+        ...(info.request_id && /^req-[A-Za-z0-9_-]+$/.test(info.request_id) ? { request_id: info.request_id } : {}),
+        ...(typeof info.retryable === 'boolean' ? { retryable: info.retryable } : {}) };
+}
 export async function run(argv, io, opts = {}) {
     const signal = opts.signal ?? new AbortController().signal;
     await registerInstalledT3(io.env, configDir(io.env), signal);
@@ -410,6 +428,7 @@ export async function run(argv, io, opts = {}) {
     const rawKey = io.env.SHARDFLUX_API_KEY;
     // Every credential this command loaded or received: redacted from anything printed on failure.
     const secrets = [rawKey ?? '', io.env.SHARDFLUX_SESSION_TOKEN ?? ''].filter((s) => s.trim().length >= 8).map((s) => s.trim());
+    let writeOnlyValueLoaded = false;
     const wantsJson = argv.slice(0, argv.includes('--') ? argv.indexOf('--') : argv.length).includes('--json');
     const cred = { keySource: null, sessionSource: null, sessionRejected: false, keyRejected: false, email: null };
     const store = new CredentialStore(configDir(io.env), (m) => void io.stderr.write(`${m}\n`));
@@ -421,7 +440,10 @@ export async function run(argv, io, opts = {}) {
     let command = undefined;
     const report = (err) => {
         const code = exitCodeFor(err, signal.aborted);
-        const info = describeError(err);
+        const described = describeError(err);
+        // A proxy or validation error can echo any submitted value, including a one-byte credential or JSON escapes.
+        // Keep structured output valid and preserve the status/request id without copying remote prose or details.
+        const info = writeOnlyValueLoaded ? credentialFailure(described) : described;
         if (code === EXIT.interrupted && info.code !== 'interrupted') {
             info.code = 'interrupted';
             info.message = 'Interrupted.';
@@ -439,7 +461,7 @@ export async function run(argv, io, opts = {}) {
             }
         }
         // An error that knows the command to continue with (an interrupted or still running execution) brings its own hint.
-        const own = ownHint(err) ?? ((err instanceof InterruptedError || err instanceof ExecutionPendingError) && err.hint ? err.hint : undefined);
+        const own = writeOnlyValueLoaded ? undefined : ownHint(err) ?? ((err instanceof InterruptedError || err instanceof ExecutionPendingError) && err.hint ? err.hint : undefined);
         const hint = command === 'feedback' ? feedbackHint(info, own ?? hintFor(info, cred, store.file, command)) : (own ?? hintFor(info, cred, store.file, command));
         // --timing on a failure: the failed call's timing (err.timing, else the last recorded), before the error; with
         // --json a `timing` field next to `error`.
@@ -669,6 +691,12 @@ export async function run(argv, io, opts = {}) {
                 if (value.length >= 8)
                     secrets.push(value);
             },
+            addWriteOnlyValue(value) {
+                if (value.length)
+                    writeOnlyValueLoaded = true;
+                if (value.length >= 8)
+                    secrets.push(value);
+            },
             async versionStatus(force) {
                 const check = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent, registry: npmRegistry(io.env) });
                 if (!force && updateCheckDisabled(io.env)) {

package/dist/orchestrator-args.js

@@ -3,11 +3,21 @@ const ORG = {
 };
 const WHO = 'Your orchestrator is yours: one agent on its own Shardflux computer, the same on every device. Uses your signed-in session, or SHARDFLUX_API_KEY when it is set (a project key you created: a new orchestrator is filed under its project).';
 export const ORCHESTRATOR_COMMANDS = [
+    {
+        path: ['orchestrator', 'show'],
+        summary: 'Read an input and its device-request outcomes, failures first',
+        positionals: [{ name: 'input-id', required: true }],
+        options: ORG,
+        description: 'Shows the input and durable requests made by its thread, including what ran, local and remote paths, exit codes and recorded errors. Reading starts no computer. A thread can also hear follow-ups; each JSON request identifies its conversation. With --json: {input, device_requests}.',
+        examples: ['shard orchestrator show in_abcdefghijklmnopqrstuvwxyz', 'shard orchestrator show in_abcdefghijklmnopqrstuvwxyz --json'],
+    },
     {
         path: ['orchestrator', 'say'],
         summary: 'Say something to your orchestrator; one of its threads hears each input at once (0.27.0+)',
-        positionals: [{ name: 'words', variadic: true, words: true, required: true }],
+        positionals: [{ name: 'words', variadic: true, words: true, required: false }],
         options: {
+            file: { type: 'string', multiple: true, value: '<path|->', description: 'Attach a file (repeatable); - streams standard input as a file.' },
+            'file-name': { type: 'string', value: '<name>', description: 'The name of the standard-input file (default stdin).' },
             task: { type: 'string', value: '<task-id>', description: 'Point at a task (task_…).' },
             report: { type: 'string', value: '<report-id>', description: 'Point at a report (rep_…).' },
             'needs-you': { type: 'string', value: '<item-id>', description: 'Point at something that waits on you (perm_…, oq_…).' },

package/dist/orchestrator-commands.js

@@ -6,6 +6,9 @@
  * a session) reaches the orchestrator of the member who created that key (person-scope.ts). Text output is one line
  * per input, tab-separated, id first; --json prints the API's objects.
  */
+import { mkdtemp, open, unlink, rmdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, basename } from 'node:path';
 import { inputSettled } from '@shardflux/sdk';
 import { parseDuration } from "./args.js";
 import { out, str } from "./commands.js";
@@ -13,6 +16,7 @@ import { EXIT, UsageError } from "./errors.js";
 import { humanBytes } from "./files-mirror.js";
 import { inScope } from "./person-scope.js";
 import { progress } from "./progress.js";
+import { deviceOutcomeLines } from "./device-outcomes.js";
 /** --wait's default: how long `say --wait` follows an input before it stops (the input goes on). */
 export const SAY_WAIT_MS = 10 * 60_000;
 const oneLine = (s, max) => {
@@ -198,17 +202,54 @@ const idOf = (id) => {
     return id;
 };
 export const ORCHESTRATOR_HANDLERS = {
+    async 'orchestrator show'(ctx, values, [id]) {
+        const detail = await inScope(ctx, values, (client, scope) => client.orchestrator.input(idOf(id), { ...orgOnly(scope), signal: ctx.signal }));
+        out(ctx, [`${detail.input.id}\t${stateLabel(detail.input)}`, resultText(detail.input), ...deviceOutcomeLines(detail.device_requests)].filter(Boolean).join('\n') + '\n', detail);
+        return EXIT.ok;
+    },
     async 'orchestrator say'(ctx, values, words) {
         const text = words.join(' ');
-        if (!text.trim())
-            throw new UsageError('missing <words...> for "shard orchestrator say"');
+        const paths = Array.isArray(values.file) ? values.file : typeof values.file === 'string' ? [values.file] : [];
+        if (!text.trim() && !paths.length)
+            throw new UsageError('missing <words> for "shard orchestrator say"');
         const selection = selectionOf(values);
         const wait = values.wait === true;
         const timeoutMs = str(values.timeout) === undefined ? SAY_WAIT_MS : parseDuration(str(values.timeout), 'timeout');
         if (!wait && str(values.timeout) !== undefined)
             throw new UsageError('--timeout goes with --wait.');
         return inScope(ctx, values, async (client, scope) => {
-            const input = await client.orchestrator.say(text, { ...orgOnly(scope), ...(selection ? { selection } : {}), signal: ctx.signal });
+            let spool;
+            let input;
+            const files = [];
+            try {
+                for (const path of paths) {
+                    if (path !== '-') {
+                        files.push({ path, name: basename(path) });
+                        continue;
+                    }
+                    if (!spool) {
+                        spool = await mkdtemp(join(ctx.io.env.HOME ?? tmpdir(), 'shard-input-'));
+                        const sink = await open(join(spool, 'stdin'), 'wx', 0o600);
+                        try {
+                            for await (const chunk of ctx.io.stdin) {
+                                ctx.signal.throwIfAborted();
+                                await sink.writeFile(chunk);
+                            }
+                        }
+                        finally {
+                            await sink.close();
+                        }
+                    }
+                    files.push({ path: join(spool, 'stdin'), name: str(values['file-name']) ?? 'stdin' });
+                }
+                input = await client.orchestrator.say({ text, files, ...orgOnly(scope), ...(selection ? { selection } : {}), signal: ctx.signal });
+            }
+            finally {
+                if (spool) {
+                    await unlink(join(spool, 'stdin')).catch(() => undefined);
+                    await rmdir(spool);
+                }
+            }
             if (!wait) {
                 out(ctx, `${input.id}\t${stateLabel(input)}\n`, { input });
                 return EXIT.ok;

package/dist/task-auto-land.d.ts

@@ -0,0 +1,22 @@
+import type { NeedsYouItem } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import type { LandDeps } from './land.js';
+interface TaskAutoLandOptions {
+    needs(signal: AbortSignal): Promise<NeedsYouItem[]>;
+    land: LandDeps;
+    enabled(project: string): boolean;
+    log(line: string): void;
+    now?: () => number;
+    stateDir?: string;
+}
+export declare class TaskAutoLand {
+    #private;
+    readonly options: TaskAutoLandOptions;
+    constructor(options: TaskAutoLandOptions);
+    /** One serial pass. A conflict waits for a new result; a disconnected/busy folder or failed receipt retries. */
+    tick(signal: AbortSignal): Promise<void>;
+}
+/** Only projects actually linked on this computer; a task's repository is checked again before any VM is opened. */
+export declare function taskLandProjects(ctx: Ctx): string[];
+export declare function runTaskAutoLand(ctx: Ctx): Promise<void>;
+export {};

package/dist/task-auto-land.js

@@ -0,0 +1,162 @@
+/** Finished board tasks reach their linked folders even with the desktop board closed (next CLI release). */
+import { setTimeout as delay } from 'node:timers/promises';
+import { conversationClient } from "./conversation-commands.js";
+import { localConversations } from "./conversations.js";
+import { landDeps, landTask } from "./land.js";
+import { selectedProjects } from "./project-preparation.js";
+import { TwinLedger } from "./worktree-twin.js";
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { writePrivateFile } from "./credentials.js";
+export class TaskAutoLand {
+    #attempts = new Map();
+    options;
+    constructor(options) {
+        this.options = options;
+        if (options.stateDir) {
+            try {
+                const rows = JSON.parse(readFileSync(join(options.stateDir, 'task-auto-land.json'), 'utf8'));
+                for (const [id, row] of Object.entries(rows))
+                    if (typeof row.key === 'string' && Number.isSafeInteger(row.tries)
+                        && Number.isFinite(row.retryAt) && typeof row.blocked === 'boolean')
+                        this.#attempts.set(id, row);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+    #save() {
+        if (this.options.stateDir)
+            writePrivateFile(this.options.stateDir, join(this.options.stateDir, 'task-auto-land.json'), JSON.stringify(Object.fromEntries(this.#attempts)) + '\n');
+    }
+    /** One serial pass. A conflict waits for a new result; a disconnected/busy folder or failed receipt retries. */
+    async tick(signal) {
+        const now = this.options.now ?? Date.now, needs = await this.options.needs(signal);
+        // Keep the result key through disconnects and service restarts. A missing discovery page is not permission to
+        // repeat a conflict's steer or an already recorded landing. A master's next done report has a new key.
+        for (const item of needs) {
+            if (signal.aborted)
+                return;
+            if (item.kind !== 'land' || !item.task_id || !item.project_id || !this.options.enabled(item.project_id))
+                continue;
+            const key = `${item.id}@${item.since}`, prior = this.#attempts.get(item.id);
+            if (prior?.key === key && (prior.blocked || prior.retryAt > now()))
+                continue;
+            try {
+                const result = await landTask({ ...this.options.land, signal }, item.task_id, { automatic: true });
+                if (!result.recorded)
+                    throw new Error(result.record_error ?? 'The task landing receipt was not recorded.');
+                this.#attempts.set(item.id, { key, tries: 0, retryAt: 0, blocked: true });
+                this.#save();
+                this.options.log(result.message);
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                const code = error.code;
+                const tries = prior?.key === key ? prior.tries + 1 : 1;
+                const blocked = code === 'land_conflict' || code === 'land_unrelated' || code === 'land_result_unready';
+                this.#attempts.set(item.id, { key, tries, blocked, retryAt: now() + Math.min(600_000, 1000 * 2 ** Math.min(tries, 9)) });
+                this.#save();
+                // Off and a folder on another computer need no warning. The existing one-per-task land item stays intact.
+                if (code !== 'land_automatic_off' && code !== 'land_device_unlinked')
+                    this.options.log(`Task ${item.task_id}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+}
+/** Only projects actually linked on this computer; a task's repository is checked again before any VM is opened. */
+export function taskLandProjects(ctx) {
+    const profile = ctx.store.profile(ctx.apiUrl), fallback = profile.project_id ?? profile.api_key?.project_id;
+    return [...new Set([
+            ...selectedProjects(ctx).map(p => p.project_id ?? fallback),
+            ...Object.values(localConversations(ctx)).filter(c => !c.handed_off).map(c => c.project_id),
+        ].filter((p) => Boolean(p)))];
+}
+export async function runTaskAutoLand(ctx) {
+    if (ctx.signal.aborted)
+        return;
+    const client = conversationClient(ctx), ledger = new TwinLedger(ctx.store.dir);
+    const profile = ctx.store.profile(ctx.apiUrl);
+    const key = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || profile.api_key !== undefined;
+    const log = (line) => { ctx.io.stderr.write(line + '\n'); };
+    const needs = new Map();
+    const watches = new Map();
+    const engine = new TaskAutoLand({
+        land: landDeps(ctx), enabled: project => ledger.mode(project) === 'auto', log, stateDir: ctx.store.dir,
+        needs: () => Promise.resolve([...needs.values()].flat()),
+    });
+    let landing, again = false;
+    const kick = () => {
+        again = true;
+        if (!landing)
+            landing = (async () => {
+                while (again && !ctx.signal.aborted) {
+                    again = false;
+                    await engine.tick(ctx.signal);
+                }
+            })().catch(error => { if (!ctx.signal.aborted)
+                log(`Task landing: ${error instanceof Error ? error.message : String(error)}`); })
+                .finally(() => { landing = undefined; });
+        return landing;
+    };
+    const follow = async (projectId, signal) => {
+        let failures = 0;
+        while (!signal.aborted) {
+            try {
+                const organizationId = key ? undefined : (await ctx.account().projects.get(projectId)).organization_id;
+                const scope = { projectId, ...(organizationId ? { organizationId } : {}), signal };
+                // Read once (including results that finished while offline), then use the held feed. No repeated whole-board
+                // reads while idle, and a slow project's feed cannot delay another project's landing or device heartbeats.
+                const board = await client.board.get(scope);
+                needs.set(projectId, board.needs_you);
+                void kick();
+                failures = 0;
+                for await (const update of client.board.watch({ ...scope, cursor: board.cursor })) {
+                    if (update.reset)
+                        needs.set(projectId, update.board.needs_you);
+                    else if (update.needs_you !== null)
+                        needs.set(projectId, update.needs_you);
+                    void kick();
+                }
+                if (!signal.aborted)
+                    throw new Error('The board feed ended before its device helper stopped.');
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                log(`Task landing discovery: ${error instanceof Error ? error.message : String(error)}`);
+                await delay(Math.min(60_000, 1000 * 2 ** Math.min(failures++, 6)), undefined, { signal }).catch(() => undefined);
+            }
+        }
+    };
+    try {
+        while (!ctx.signal.aborted) {
+            const projects = new Set(taskLandProjects(ctx).filter(p => ledger.mode(p) === 'auto'));
+            for (const [project, watch] of watches)
+                if (!projects.has(project)) {
+                    watch.abort.abort();
+                    await watch.work;
+                    watches.delete(project);
+                    needs.delete(project);
+                }
+            for (const project of projects)
+                if (!watches.has(project)) {
+                    const abort = new AbortController(), signal = AbortSignal.any([ctx.signal, abort.signal]);
+                    const work = follow(project, signal);
+                    watches.set(project, { abort, work });
+                }
+            // The local setting and deferred folder/receipt retries do not wait for a remote board event.
+            await kick();
+            await delay(2000, undefined, { signal: ctx.signal }).catch(() => undefined);
+        }
+    }
+    finally {
+        for (const watch of watches.values())
+            watch.abort.abort();
+        await Promise.all([...watches.values()].map(w => w.work));
+        await landing;
+    }
+}

package/dist/task-land-hub.py

@@ -106,6 +106,12 @@ def land(a):
         have = {b: tip(work, 'refs/heads/' + b) for b in wanted}
         before = have.get(into)
         t, created = have.get(result), False
+        if a.get('require_result'):
+            if not t:
+                return {'state': 'unready', 'into': into, 'reason': 'result_missing'}
+            missing = [s for s in sources if not have.get(s) or not ancestor(work, have[s], t)]
+            if missing:
+                return {'state': 'unready', 'into': into, 'reason': 'workers_not_integrated', 'unintegrated': missing}
         if not t:
             # A master that did not merge its workers: merge them here, each only when it merges cleanly.
             for s in sources:

package/dist/vault.js

@@ -28,20 +28,15 @@ export function vaultOutput(vault, name, options = {}) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'ignore'], env: options.env, signal: options.signal });
         const chunks = [];
-        let size = 0;
         let failed = false;
         const timer = setTimeout(() => {
             failed = true;
             child.kill('SIGKILL');
         }, 30_000);
         child.stdout.on('data', (chunk) => {
-            size += chunk.length;
-            if (size > 65_538) {
-                failed = true;
-                child.kill('SIGKILL');
-            }
-            else
-                chunks.push(chunk);
+            // Provider JSON includes metadata as well as the selected value. Enforce the secret store's value limit
+            // after extraction; a transport cap here rejected valid small values in larger items.
+            chunks.push(chunk);
         });
         child.on('error', () => {
             clearTimeout(timer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.28.2",
+  "version": "0.28.3",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -53,7 +53,7 @@
     "snappyjs": "0.7.0",
     "ws": "8.22.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.30.2"
+    "@shardflux/sdk": "^0.30.3"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -65,10 +65,10 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/desktop-darwin-arm64": "0.9.3",
-    "@shardflux/desktop-darwin-x64": "0.9.3",
-    "@shardflux/desktop-linux-arm64": "0.9.3",
-    "@shardflux/desktop-linux-x64": "0.9.3"
+    "@shardflux/desktop-darwin-arm64": "0.9.4",
+    "@shardflux/desktop-darwin-x64": "0.9.4",
+    "@shardflux/desktop-linux-arm64": "0.9.4",
+    "@shardflux/desktop-linux-x64": "0.9.4"
   },
   "scripts": {
     "build": "node scripts/build.mjs",