@shardflux/cli 0.28.2 → 0.28.4

package/dist/device-helper.js

@@ -1,5 +1,6 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import { DeviceExecutor, askConnectedAcp, askDeviceApprover } from "./device-bridge.js";
+import { credentialHeartbeat } from "./credential-device-capability.js";
 import { ShardfluxApiError } from '@shardflux/sdk';
 import { allOrgs, allProjects } from "./account-scope.js";
 import { ConversationMirrorState, mirrorProjectConversations } from "./conversation-stash.js";
@@ -17,13 +18,16 @@ import { AgentConfigReturnState, runAgentConfigLoop } from "./agent-config-retur
 import { askLocalDeviceApproval } from "./device-approvals.js";
 import { resumeCloudStartup, startCarried } from "./codex-cloud.js";
 import { runProjectPreparation } from "./project-preparation.js";
+import { runTaskAutoLand } from "./task-auto-land.js";
 /** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
 export async function runDeviceHelper(ctx, options = {}) {
     const abort = new AbortController(), signal = AbortSignal.any([ctx.signal, abort.signal]);
     ctx = { ...ctx, signal };
     const pending = new Map();
-    const inputSource = Readable.from(ctx.io.stdin, { objectMode: false, signal });
-    const input = options.service ? Promise.resolve() : (async () => {
+    // A service never reads approvals from stdin. In particular the Linux fallback may start after its command has
+    // already finished: creating an unconsumed stream with that aborted signal emits an uncaught AbortError.
+    const inputSource = options.service ? undefined : Readable.from(ctx.io.stdin, { objectMode: false, signal });
+    const input = inputSource ? (async () => {
         let tail = '';
         for await (const bytes of inputSource) {
             tail += Buffer.from(bytes).toString();
@@ -40,7 +44,7 @@ export async function runDeviceHelper(ctx, options = {}) {
                 }
             }
         }
-    })().finally(() => abort.abort());
+    })().finally(() => abort.abort()) : Promise.resolve();
     void input.catch(() => abort.abort());
     // `until` ends one question early: the person chose a mode that lets the request run by itself (device-mode.ts).
     const ask = async (approval, until) => {
@@ -81,11 +85,14 @@ export async function runDeviceHelper(ctx, options = {}) {
     // sign-in change later renews again and a refusal right after a renewal stops (never a loop).
     let renewedAt = 0;
     const report = (e) => { ctx.io.stderr.write(`Device bridge: ${e instanceof Error ? e.message : String(e)}\n`); };
-    let mirroring, twin, returning, preparing, projects;
+    let mirroring, twin, returning, preparing, projects, taskLanding;
     try {
         return await withTargetLock(join(ctx.store.dir, 'device-helper-lock'), async () => {
             // Finished conversations land in their local branches (worktree-twin-engine.ts); its own loop and backoff.
             twin = runWorktreeTwin(ctx, deviceId, signal).catch(report);
+            // Board tasks (including those delegated from the phone) have no locally started conversation. Consume their
+            // finished results independently, through the exact same merge/check/receipt path as `shard task land`.
+            taskLanding = runTaskAutoLand(ctx).catch(report);
             // Skills, memories and CLAUDE.md lines saved in the cloud come back on their own cadence (agent-config-return.ts):
             // never behind a files-mirror pass, which takes minutes for an account with hundreds of conversations. Every 2 s
             // while one of this user's conversations is active, backing off to 60 s when none is.
@@ -161,13 +168,13 @@ export async function runDeviceHelper(ctx, options = {}) {
             // This device's local conversations of a project (started here or opened here): their requests come here first.
             const linked = (projectId) => Object.values(localConversations(ctx)).filter(r => !r.handed_off && (!projectId || r.project_id === projectId))
                 .sort((a, b) => (b.conversation.created_at ?? '').localeCompare(a.conversation.created_at ?? '')).slice(0, 500).map(r => r.conversation.id);
-            const beat = (projectId) => conversationClient(ctx).deviceRequests.heartbeat({ ...(projectId ? { projectId } : {}), deviceId, leaseSeconds: 30, ...(links ? { conversationIds: linked(projectId) } : {}) })
+            const beat = (projectId) => credentialHeartbeat(ctx, { ...(projectId ? { projectId } : {}), deviceId, leaseSeconds: 30, ...(links ? { conversationIds: linked(projectId) } : {}) })
                 .catch((e) => {
                 // An API before device links (0.25.0+ clients) refuses the list: register without it from then on.
                 if (!links || !(e instanceof ShardfluxApiError && [400, 422].includes(e.status)))
                     throw e;
                 links = false;
-                return conversationClient(ctx).deviceRequests.heartbeat({ ...(projectId ? { projectId } : {}), deviceId, leaseSeconds: 30 });
+                return credentialHeartbeat(ctx, { ...(projectId ? { projectId } : {}), deviceId, leaseSeconds: 30 });
             });
             const take = (rows) => {
                 for (const r of rows) {
@@ -261,7 +268,7 @@ export async function runDeviceHelper(ctx, options = {}) {
     }
     finally {
         abort.abort();
-        inputSource.destroy();
+        inputSource?.destroy();
         for (const resolve of pending.values())
             resolve('deny');
         pending.clear();
@@ -273,6 +280,7 @@ export async function runDeviceHelper(ctx, options = {}) {
         await twin;
         await preparing;
         await projects;
+        await taskLanding;
         await input.catch(() => undefined);
     }
 }

package/dist/device-mode.d.ts

@@ -38,7 +38,14 @@ export interface DeviceActivity {
     local_path?: string;
     exit_code?: number;
     finished_at?: string;
+    error?: string;
 }
 export declare function recordDeviceActivity(dir: string, entry: DeviceActivity): void;
+/** Persist the result before posting it: a stopped helper or failed API call must not erase the actual device error. */
+export declare function recordDeviceResult(dir: string, entry: DeviceActivity, result: {
+    state: DeviceActivity['state'];
+    exit_code?: number;
+    stderr_b64?: string;
+}): void;
 /** What ran without asking, newest first: one entry per request with its latest state. */
 export declare function deviceActivity(dir: string, limit?: number): DeviceActivity[];

package/dist/device-mode.js

@@ -87,6 +87,19 @@ export function recordDeviceActivity(dir, entry) {
     }
     catch { /* the request's own result still reaches its conversation */ }
 }
+/** Persist the result before posting it: a stopped helper or failed API call must not erase the actual device error. */
+export function recordDeviceResult(dir, entry, result) {
+    const bytes = result.stderr_b64 ? Buffer.from(result.stderr_b64, 'base64') : null;
+    let error;
+    if (bytes && bytes.toString('base64').replace(/=+$/, '') === result.stderr_b64.replace(/=+$/, '')) {
+        try {
+            error = new TextDecoder('utf-8', { fatal: true }).decode(bytes) || undefined;
+        }
+        catch { /* no readable error text */ }
+    }
+    recordDeviceActivity(dir, { ...entry, at: new Date().toISOString(), state: result.state,
+        ...(result.exit_code !== undefined ? { exit_code: result.exit_code } : {}), ...(error !== undefined ? { error } : {}) });
+}
 /** What ran without asking, newest first: one entry per request with its latest state. */
 export function deviceActivity(dir, limit = 20) {
     let text;

package/dist/device-outcomes.d.ts

@@ -0,0 +1,3 @@
+import type { DeviceRequestOutcome } from '@shardflux/sdk';
+/** The actual request and its outcome, never shortened to a count or a generic failure. */
+export declare function deviceOutcomeLines(requests: readonly DeviceRequestOutcome[]): string[];

package/dist/device-outcomes.js

@@ -0,0 +1,19 @@
+/** The actual request and its outcome, never shortened to a count or a generic failure. */
+export function deviceOutcomeLines(requests) {
+    if (!requests.length)
+        return [];
+    const ordered = [...requests].sort((a, b) => Number(b.failed) - Number(a.failed) || Date.parse(b.created_at) - Date.parse(a.created_at) || b.id.localeCompare(a.id));
+    return ['', 'Device requests', ...ordered.flatMap(r => {
+            const state = r.failed ? 'failed' : r.state;
+            const lines = [`${r.id}\t${state}${typeof r.exit_code === 'number' ? ` (exit ${r.exit_code})` : ''}\t${r.what}`];
+            if (r.path)
+                lines.push(`  Local: ${r.path}`);
+            if (r.remote_path)
+                lines.push(`  Remote: ${r.remote_path}`);
+            if (r.error)
+                lines.push(`  ${r.error}`);
+            else if (r.failed)
+                lines.push('  Error text unavailable');
+            return lines;
+        })];
+}

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 capabilities", "orchestrator show", "orchestrator say", "orchestrator list", "orchestrator history", "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,35 @@ 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', 'capabilities'],
+        summary: 'Read current input file support for your recipient',
+        positionals: [], options: ORG,
+        description: 'Reads your recipient metadata without creating or waking a computer. With --json: {capabilities: {input_files}}.',
+        examples: ['shard orchestrator capabilities --json'],
+    },
+    {
+        path: ['orchestrator', 'history'],
+        summary: 'Page through every input, including old and dismissed answers',
+        positionals: [],
+        options: { cursor: { type: 'string', value: '<cursor>', description: 'The previous page’s next_cursor.' }, limit: { type: 'string', value: '<n>', description: 'Page size, 1-200 (default 100).' }, ...ORG },
+        description: 'Reads one chronological page without starting work or waking a computer. Follow next_cursor to read earlier inputs. With --json: {inputs, next_cursor}.',
+    },
+    {
+        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,13 +6,17 @@
  * 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";
+import { listLimit, out, str } from "./commands.js";
 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,59 @@ const idOf = (id) => {
     return id;
 };
 export const ORCHESTRATOR_HANDLERS = {
+    async 'orchestrator capabilities'(ctx, values) {
+        const capabilities = await inScope(ctx, values, (client, scope) => client.orchestrator.capabilities({ ...orgOnly(scope), signal: ctx.signal }));
+        out(ctx, `input_files\t${capabilities.input_files}\n`, { capabilities });
+        return EXIT.ok;
+    },
+    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;
@@ -242,6 +288,15 @@ export const ORCHESTRATOR_HANDLERS = {
         out(ctx, human, { inputs: page.inputs ?? [], cursor: page.cursor });
         return EXIT.ok;
     },
+    async 'orchestrator history'(ctx, values) {
+        const limit = listLimit(values, 200);
+        const page = await inScope(ctx, values, (client, scope) => client.orchestrator.history({ ...orgOnly(scope), cursor: str(values.cursor), ...(limit !== undefined ? { limit } : {}), signal: ctx.signal }));
+        const lines = page.inputs.map(inputLine);
+        if (page.nextCursor)
+            lines.push(`Next page: shard orchestrator history --cursor ${page.nextCursor}`);
+        out(ctx, lines.length ? `${lines.join('\n')}\n` : 'No input history yet.\n', { inputs: page.inputs, next_cursor: page.nextCursor });
+        return EXIT.ok;
+    },
     async 'orchestrator retry'(ctx, values, [id]) {
         const input = await inScope(ctx, values, (client, scope) => client.orchestrator.retry(idOf(id), { ...orgOnly(scope), signal: ctx.signal }));
         out(ctx, `${input.id}\t${stateLabel(input)}\n`, { input });

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 {};