@shardflux/cli 0.28.2 → 0.28.4

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 ## Unreleased
 
+- Keep queued messages moving after an obsolete computer upgrade choice is cleared or changed; offer only compatible computer upgrades.
+
+## 0.28.4
+
+- Pending native conversation messages keep their original sequence until acknowledged, including across a paused computer or an API restart. The retained computer wakes through its existing authorized path.
+
+- Available workspace updates use the current saved machine or project environment, matching the target applied by an update after a saved-version rollback.
+
+- Conversation moves require a saved checkpoint when idle. A new turn releases an incomplete idle move while keeping its computer, session, files and queued messages; active turns keep their deferred move.
+
+- Read older and dismissed orchestrator answers with `shard orchestrator history`; `--cursor`, `--limit`, and `--organization` select a read-only page. JSON returns `inputs` and `next_cursor`.
+
+- Home computer updates select the organization’s current saved machine, including after a machine rollback; repository and explicit update targets keep their existing behavior. Request and response fields are unchanged.
+
+- Read current recipient input-file capability through the authenticated orchestrator API; unsupported file requests return a retryable update action, and pending file delivery keeps its actual waiting reason.
+
+- Orchestrator dismissal: the API keeps dismissed, unstarted inputs out of dispatch and queue positions until they are restored. Work that already started continues; request and response fields are unchanged.
+
+- Folder starts (0.28.4+): an agent's `project_link` with a first prompt (the device helper) never stays running: a start from the folder that does not finish within 5 minutes fails with what held it (for example `Setting up <project>: saving template`), and a start process that ignores its stop is killed 10 seconds later.
+
+- The Shardflux app 0.9.5 (0.28.4+): `shard` installs and updates `@shardflux/desktop-darwin-arm64` / `-x64` and
+  `@shardflux/desktop-linux-x64` / `-arm64` 0.9.5 (a three-step first run, ⌘2 History search, request details
+  from your computer, full-screen pictures and videos on a phone, agents that stay in view, New project and Sign
+  out on the web, talking on Android and with several organizations).
+
+- Cloud input-file delivery (0.28.4+, SDK 0.30.4): native-route refusals preserve `codex_cloud_input_files_require_native`; explicit `delivery.waiting` returns immediately with its reason and message, and is never reported as delivered.
+
+- Settled reason (0.28.4+, SDK 0.30.4): preserve optional `settled_reason` on conversations and agents: `computer_suspended` identifies a computer that froze an active turn; `computer_failed` identifies a failed computer. Absent/null does not establish completion.
+
+- Orchestrator usage waits (0.28.4+, SDK 0.30.4): orchestrator waits preserve optional input `waiting.reason` / `waiting.until` and orchestrator `waiting.until`; queued state and queue position stay unchanged. Message-only waits from older APIs remain compatible.
+
+- Credential imports (0.28.4+): queue bulk credential imports instead of opening every local source and upload together. Every selected source is processed, and an individual failure does not stop the others.
+
+- The Shardflux app 0.9.4 (0.28.3+): `shard` installs and updates `@shardflux/desktop-darwin-arm64` / `-x64` and
+  `@shardflux/desktop-linux-x64` / `-arm64` 0.9.4 (files with a ⌘2 task, ⌘2 Credentials and Set up from this Mac,
+  talking in Safari, new answers stay visible, device request outcomes).
+
+- Device request outcomes (0.28.3+, SDK 0.30.3): `shard orchestrator show <input-id>` and `shard task show <task-id>` show device requests, paths and recorded errors, failures first. Device activity keeps the actual error before API delivery.
+
+- Input attachments (0.28.3+, SDK 0.30.3): `shard orchestrator say --file <path>` attaches files; repeat the flag, or use `--file - --file-name <name>` to stream stdin. Files-only inputs are supported.
+
+- Automatic task landing (0.28.3+): the device helper automatically lands a finished board task's tested result in its linked repository even when the desktop board is closed. It respects Auto land and project landing settings, keeps local edits, waits for a missing folder, retries an interrupted receipt, and records the board only after delivery. Conflicts and unfinished master integration wait for a new result instead of repeating a steer after a service restart.
+
+- Linux helper shutdown (0.28.3+): short Linux commands shut down their command-lifetime helper cleanly; service helpers leave stdin with the foreground command.
+
+- Task results (0.28.3+, SDK 0.30.3): keep canonical task-result links and automatic resend metadata in orchestrator input output.
+
+- Coordinator questions (0.28.3+, SDK 0.30.3): input reads preserve a coordinator wait and its message; internal worker blockers reach their coordinator before a question reaches the person. Existing needs-you answer commands remain unchanged.
+
+- Credential setup (0.28.3+, SDK 0.30.3): `shard credentials setup --from-this-computer` brings existing shell, project and login credentials along automatically. `--if-needed` leaves unchanged values alone; `--plan` offers an optional names-only review. Connected agents can request the same secure local transfer through the device helper.
+
+- Credential errors (0.28.3+): write-only credential failures never copy upstream prose or details into output, including values shorter than eight bytes and JSON-escaped values. Status and request id remain available.
+
 - The Shardflux app 0.9.3 (0.28.2+): `shard` installs and updates `@shardflux/desktop-darwin-arm64` / `-x64` and
   `@shardflux/desktop-linux-x64` / `-arm64` 0.9.3 (files open beside your work, pictures and videos picture in picture,
   ⌘2 shows the agents your orchestrator starts, needs-you questions read whole).

package/README.md

@@ -1,5 +1,7 @@
 # @shardflux/cli: `shard`
 
+Queued messages retain their computer and native session when a pending upgrade choice is cleared or changed.
+
 Use `shard --help` or `shard <command> --help` to explore commands before signing in.
 
 For error codes, retry timing, and plan recovery, see the [error reference](https://docs.shardflux.dev/reference/errors).
@@ -101,7 +103,7 @@ and restarts after a CLI update. It keeps the live twin, `~/Shardflux` files and
 Use `shard device requests`, `shard device approve <id>` or `shard device deny <id>` for local approvals, and
 `shard device approvals auto|read|ask` to choose whether your agents ask first (0.28.0+);
 desktop notifications point to pending requests. On systems without a systemd user session, the helper runs
-while your `shard` commands are open. `shard agents open` opens a terminal when launched outside one, using
+while your `shard` commands are open; their input stays with the foreground command. `shard agents open` opens a terminal when launched outside one, using
 `$TERMINAL`, `x-terminal-emulator` or `gnome-terminal`, or prints the attach command. On macOS the same app lives in
 the menu bar.
 
@@ -263,6 +265,9 @@ Finished cloud work lands in your folder by itself: a conversation's commits com
 board task's result into your linked folder and the project's default branch. `shard settings --auto-land off`
 (0.28.0+) keeps it in the cloud on this computer (`shard task land` and `shard conversations land` still land on
 request); `--auto-land on` turns it back on. The Shardflux app's Settings → Projects changes the same switch.
+The device helper brings finished task results back while your computer is reachable, including work requested from
+your phone; it catches up after your computer reconnects. Your local edits stay in place, and a conflicting merge
+waits for a decision instead of overwriting them.
 
 Terminal conversations open in the terminal you choose (0.22.0+):
 
@@ -1529,8 +1534,10 @@ your agent uses the matching machine or project save/rollback commands in its so
 `shard machine open` (0.17.1+): it creates or resumes the machine VM without attaching and prints its key for
 `shard ws exec` and `shard files write`. `shard machine setup --from-this-computer` (0.20.0+) does it for you: your own
 Claude Code (`claude -p`, else Codex) recreates this computer's CLIs and tools, language runtimes, shell config and
-aliases, git identity and dotfiles on the machine, on your subscription, then saves it. On this computer it only reads;
-`~/.ssh`, keychains, `.env`, token and credential files are never read. The apps and the first run start it once,
+aliases, git identity and dotfiles on the machine, on your subscription, then saves it. That setup agent reads
+tool and configuration metadata and excludes `~/.ssh`, keychains, `.env`, token and credential files. Optional
+`--with-credentials` (0.28.3+) runs the trusted local credential transfer afterwards; onboarding includes that transfer.
+The apps and the first run start machine setup once,
 right after you connect your agents. `shard machine setup --status` shows the machine as your account has it, in the
 same line the apps show: ready, saving (with its place in the queue), or the one command to run next (0.22.0+); `shard
 setup --inspect --json` carries it as `onboarding.machine`. `connections_ready` (and the legacy `ready` field) means
@@ -1719,6 +1726,8 @@ shard c delete conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --yes
 
 ### Your orchestrator (0.28.0+)
 
+A queued input (0.28.4+) can carry `waiting.message`: the platform explains what it waits for, including a known usage-reset time. Keep that line alongside its queue position while the input remains queued.
+
 `shard orchestrator say` passes your words to the API as one input, without cutting the final instruction.
 
 Your orchestrator is your own agent on top of every project, on its own Shardflux computer and the same on every
@@ -2100,3 +2109,55 @@ Bare `shard` in a coding-agent shell or without a TTY returns its setup guide us
 Needs-you output prints each question and its optional `option_details` in full, including what each choice does and what follows it. The first suggested answer is the agent’s recommendation. Secret values go through the project’s secure setup, never a question or its ordinary answer.
 
 Conversation creation (0.28.2+) includes the optional launching conversation only when `/v1/meta` advertises `capabilities.conversation_origin: true`. Older APIs receive the existing create body; no rejected create is replayed with different fields.
+
+
+## Input attachments (0.28.3+)
+
+`shard orchestrator say --file <path>` attaches files; repeat the flag, or use `--file - --file-name <name>` to stream stdin. Files-only inputs are supported.
+
+```sh
+shard orchestrator say "Review these" --file spec.pdf --file photo.png
+cat archive.tar | shard orchestrator say --file - --file-name archive.tar
+```
+File uploads stream to durable API storage, then the input carries their pinned references. Each receiving thread gets the files before its turn, under `~/inputs/`.
+
+### Device request outcomes (0.28.3+)
+
+```sh
+shard orchestrator show in_abcdefghijklmnopqrstuvwxyz
+shard task show task_abcdefghijklmnopqrstuvwxyz
+```
+
+Each request shows what ran, its paths and outcome, and its recorded error. Failures appear first. Add `--json` for the full detail object. Reading starts no computer.
+
+Scoped vault imports (0.28.3+) use `shard secrets import NAME --from hsec --scope project --project PROJECT` (or `--scope agents --org ORG` while signed in). Re-importing an identical value leaves its version unchanged; a changed value rotates it. The vault sends the value directly to the encrypted write-only API. Failures show a safe status and request id without upstream prose or details that could echo the value.
+
+## Credential setup (0.28.3+)
+
+Every selected source is processed, and an unavailable source does not stop other credentials from being imported.
+
+Run `shard credentials setup --from-this-computer --if-needed` after machine setup to bring your existing credentials along. Machine credentials are available to all your agents; project `.env` credentials stay local and override machine values by name. Values transfer directly from the local source into the write-only secret store and private credential files. The command prints names and delivery progress. Use `--plan` for an optional review, then `--apply PLAN_ID`. If a requested credential is missing everywhere, your agent asks once through the secure credential field.
+
+## Conversation delivery waits (0.28.4+)
+
+`shard conversations send --wait` prints the server’s explicit delivery-wait message; JSON retains `delivery.waiting.reason` and `message`. Route file-bearing delegated workers through native threads. Reason `codex_cloud_input_files_require_native` identifies a Cloud route that needs a native thread before the message is accepted.
+
+### Dismissed orchestrator inputs
+
+Dismiss an orchestrator input before it starts to keep it from running. Restoring that queued input puts it back in line. Dismissing an input that already started leaves its existing work running.
+
+### Home computer updates
+
+Updating a home conversation’s computer selects the organization’s current saved machine, including after a machine rollback. Repository conversations keep their project’s saved environment.
+
+### Recipient file support (0.28.4+)
+
+Run `shard orchestrator capabilities --json` to read `{capabilities: {input_files}}` for your recipient without creating or waking a computer.
+
+A conversation moves from a saved turn. A running conversation finishes its turn before moving; a new turn continues on its retained computer when an idle move has no checkpoint.
+
+Available computer updates report the same current saved machine or project environment that an update applies, including a saved version selected by rollback.
+
+Paged History (0.28.4+): Read older and dismissed orchestrator answers with `shard orchestrator history`; `--cursor`, `--limit`, and `--organization` select a read-only page. JSON returns `inputs` and `next_cursor`.
+
+Pending native conversation messages retain their original sequence until the harness acknowledges delivery, including after the computer pauses or the API restarts.

package/dist/args.d.ts

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

package/dist/args.js

@@ -15,7 +15,7 @@ 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.28.2';
+export const CLI_VERSION = '0.28.4';
 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).' },
@@ -244,6 +244,7 @@ const KEY_COMMANDS = [
     { path: ['machine', 'setup'], summary: 'Let your own Claude Code or Codex set up your machine from this computer (0.20.0+)', positionals: [], options: {
             'from-this-computer': { type: 'boolean', description: 'Recreate this computer’s development setup on your machine: its CLIs and tools, language runtimes, shell config and aliases, git identity and dotfiles. Required.' },
             'if-needed': { type: 'boolean', description: 'Only when your machine was never set up from this computer (what the apps run after onboarding).' },
+            'with-credentials': { type: 'boolean', description: 'After the machine is saved, bring existing credentials along with the trusted local credential setup.' },
             status: { type: 'boolean', description: 'Show the last setup from this computer instead of running one.' },
             agent: { type: 'string', value: '<claude|codex|cloud>', description: 'Which agent sets it up (default: this computer’s Claude Code, else its Codex, else your cloud Claude in the machine VM).' },
             timeout: { type: 'string', value: '<duration>', description: 'Time box for the agent (default 10m).' },
@@ -982,6 +983,16 @@ const KEY_COMMANDS = [
         examples: ['shard executions get acme/agent-7 build-42', 'shard ws executions get acme/agent-7 ex-6f1c2a9e-0d7b-4c1e-9a53-2b8e1f0c4d7a --wait 10m --json'],
     },
     { path: ['secrets', 'log'], summary: 'Show credential request and fill audit events', positionals: [], options: {} },
+    { path: ['credentials', 'setup'], summary: 'Bring existing credentials from this computer to your machine and project', positionals: [], options: {
+            'from-this-computer': { type: 'boolean', description: 'Discover source names locally and transfer values directly; no value goes to a model.' },
+            'if-needed': { type: 'boolean', description: 'Reconcile existing sources; report needed:false when their stored versions are unchanged.' },
+            plan: { type: 'boolean', description: 'Review the names and scopes once before transferring selected sources.' },
+            apply: { type: 'string', value: '<plan-id>', description: 'Continue a reviewed setup using its original source descriptors.' },
+            deny: { type: 'string', value: '<plan-id>', description: 'Decline a reviewed setup.' },
+            picks: { type: 'string', value: '<file|->', description: 'JSON source IDs and scopes for --apply; - reads stdin. No values.' },
+            project: { type: 'string', value: '<project-id>', description: 'Project for local credentials (default current context).' },
+            path: { type: 'string', value: '<folder>', description: 'Project folder whose .env files to discover (default current folder).' },
+        } },
     { path: ['credentials', 'list'], summary: 'Show pending login requests', positionals: [], options: {} },
     { path: ['credentials', 'enable'], summary: 'Enable credential fill in a workspace', positionals: [REF], options: {} },
     { path: ['credentials', 'deny'], summary: 'Deny a login request', positionals: [{ name: 'request-id', required: true }], options: {} },

package/dist/board-args.js

@@ -84,7 +84,8 @@ export const BOARD_COMMANDS = [
         path: ['task', 'land'],
         summary: 'Land a finished task: its result into your folder and the project’s default branch (0.25.0+)',
         positionals: [{ name: 'id', required: true }],
-        options: { path: { type: 'string', value: '<folder>', description: 'The folder to land in (default: the project’s folder on this computer, if any).' } },
+        options: { path: { type: 'string', value: '<folder>', description: 'The folder to land in (default: the project’s folder on this computer, if any).' },
+            automatic: { type: 'boolean', hidden: true, description: 'Device automatic delivery: require Auto land, a linked folder and the master’s tested result.' } },
         description: [
             'A task has one result: the branch shard/<task id>, where its master merged its workers’ branches. Landing merges it',
             'into the project’s default branch on the project hub (a fast-forward, or a merge commit when the merge is clean),',

package/dist/board-commands.js

@@ -1,3 +1,4 @@
+import { deviceOutcomeLines } from "./device-outcomes.js";
 import { findOrg, resolveOrg } from "./account-scope.js";
 import { out, principal, str, strs, readSecretValue, askSecretValue } from "./commands.js";
 import { detailLine, pickAnswers } from "./conversation-commands.js";
@@ -150,6 +151,8 @@ export function taskDetailText(d) {
                 lines.push(`  Landed: ${r.landed.how} ${r.landed.ref}`);
         }
     }
+    if (d.device_requests !== undefined)
+        lines.push(...deviceOutcomeLines(d.device_requests));
     return `${lines.join('\n')}\n`;
 }
 /** --now, --next or --later (one at most); undefined when none was given. */
@@ -350,7 +353,7 @@ export const BOARD_HANDLERS = {
         return 0;
     },
     async 'task land'(ctx, values, [id]) {
-        const o = await landTask(landDeps(ctx), id, { path: str(values.path) });
+        const o = await landTask(landDeps(ctx), id, { path: str(values.path), automatic: values.automatic === true });
         out(ctx, landedText(o), o);
         return 0;
     },
@@ -391,7 +394,7 @@ export const BOARD_HANDLERS = {
                 await findOrg(ctx.account(), organizationId);
             }
             const save = (value) => {
-                ctx.addSecret(value);
+                ctx.addWriteOnlyValue(value);
                 return cloud.needsYou.answer(id, { credential: { value, scope: target } }, { ...(organizationId ? { organizationId } : {}), signal: ctx.signal });
             };
             const value = await readSecretValue(ctx, values, item.credential.name);

package/dist/commands.d.ts

@@ -61,6 +61,8 @@ export interface Ctx {
     };
     /** A credential this command received (redacted from error output). */
     addSecret(value: string): void;
+    /** A credential value this command writes: redacted like addSecret, and failures report only status-based codes. */
+    addWriteOnlyValue(value: string): void;
     /** The update status for `shard version` (forced: ask the API now). Null when unknown. */
     versionStatus(force: boolean): Promise<UpdateView | null>;
     /** The credentials file (config directory from the environment). */

package/dist/commands.js

@@ -2349,9 +2349,9 @@ export const KEY_HANDLERS = {
         const project = agent ? null : (await principal(ctx)).project_id;
         const imported = [];
         for (const [i, name] of names.entries()) {
-            const value = await vaultValue(from, name, { signal: ctx.signal, ...(keychain ? { keychain } : {}) });
-            ctx.addSecret(value);
-            imported.push(agent ? await agent.cloud.secrets.createAgent(agent.target, { name: targets[i], value }) : await ctx.cloud().secrets.create(project, { name: targets[i], value }));
+            const value = await vaultValue(from, name, { signal: ctx.signal, env: ctx.io.env, ...(keychain ? { keychain } : {}) });
+            ctx.addWriteOnlyValue(value);
+            imported.push(agent ? await agent.cloud.secrets.importAgent(agent.target, { name: targets[i], value }) : await ctx.cloud().secrets.create(project, { name: targets[i], value }));
         }
         out(ctx, `Imported ${imported.map(s => s.name).join(', ')}. ${SECRET_SECURITY_NOTE}\n`, { data: imported, security_note: SECRET_SECURITY_NOTE });
         return 0;
@@ -2612,7 +2612,7 @@ async function agentSecretCommand(ctx, values, action, ref) {
     if (action === 'create') {
         if (!SECRET_NAME.test(ref ?? ''))
             throw new UsageError('Use an environment variable name for the credential.');
-        const value = await readSecretValue(ctx, values, ref), save = (value) => { ctx.addSecret(value); return cloud.secrets.createAgent(target, { name: ref, value, ...(str(values.description) !== undefined ? { description: str(values.description) } : {}) }); };
+        const value = await readSecretValue(ctx, values, ref), save = (value) => { ctx.addWriteOnlyValue(value); return cloud.secrets.createAgent(target, { name: ref, value, ...(str(values.description) !== undefined ? { description: str(values.description) } : {}) }); };
         const r = value !== null ? await save(value) : await askSecretValue(ctx, values, { title: `Add ${ref}`, purpose: `Saved encrypted for your agents as ${ref}.`, name: ref }, save);
         out(ctx, describe(r), r);
         return 0;
@@ -2636,7 +2636,7 @@ async function agentSecretCommand(ctx, values, action, ref) {
         return 0;
     }
     if (action === 'rotate') {
-        const value = await readSecretValue(ctx, values, r.name), save = (value) => { ctx.addSecret(value); return cloud.secrets.rotateAgent(r.id, value); };
+        const value = await readSecretValue(ctx, values, r.name), save = (value) => { ctx.addWriteOnlyValue(value); return cloud.secrets.rotateAgent(r.id, value); };
         const changed = value !== null ? await save(value) : await askSecretValue(ctx, values, { title: `New value for ${r.name}`, purpose: `Replaces the encrypted credential ${r.name}.`, name: r.name }, save);
         out(ctx, describe(changed), changed);
         return 0;

package/dist/conversation-commands.js

@@ -87,6 +87,8 @@ const sentLines = (r) => `${r.restored ? 'Restored\n' : ''}${(r.files ?? []).map
 export const SEND_WAIT_MS = 60_000;
 /** What happened to a sent message, as `conversations send --wait` prints it (0.27.0+). */
 export function deliveryLine(d) {
+    if (d.waiting)
+        return d.waiting.message;
     if (d.state === 'pending')
         return 'Not delivered yet.';
     if (d.state === 'uncertain')

package/dist/credential-device-capability.d.ts

@@ -0,0 +1,8 @@
+import type { Ctx } from './commands.js';
+import { conversationClient } from './conversation-commands.js';
+type Input = Parameters<ReturnType<typeof conversationClient>['deviceRequests']['heartbeat']>[0];
+export declare function credentialHeartbeat(ctx: Ctx, input: Input): Promise<{
+    device_id: string;
+    online_until: string;
+}>;
+export {};

package/dist/credential-device-capability.js

@@ -0,0 +1,21 @@
+/** Old APIs must keep accepting ordinary helper heartbeats during a rolling upgrade. */
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { conversationClient } from "./conversation-commands.js";
+const probes = new WeakMap();
+export async function credentialHeartbeat(ctx, input) {
+    let probe = probes.get(ctx);
+    if (!probe || Date.now() - probe.at >= 30_000) {
+        probe = { at: Date.now(), pending: conversationClient(ctx).credentialSetups.available().catch(() => false) };
+        probes.set(ctx, probe);
+    }
+    const available = await probe.pending, cloud = conversationClient(ctx);
+    try {
+        return await cloud.deviceRequests.heartbeat({ ...input, ...(available ? { capabilities: ['credentials_setup.v1'] } : {}) });
+    }
+    catch (e) {
+        if (!available || !(e instanceof ShardfluxApiError && [400, 422].includes(e.status)))
+            throw e;
+        probes.set(ctx, { at: Date.now(), pending: Promise.resolve(false) });
+        return cloud.deviceRequests.heartbeat(input);
+    }
+}

package/dist/credential-setup.d.ts

@@ -0,0 +1,12 @@
+import type { CredentialSetup, CredentialSetupsApi } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+import type { CredentialDiscoveryOptions } from './credential-sources.js';
+type TransferContext = Pick<Ctx, 'json' | 'io' | 'signal' | 'addWriteOnlyValue'>;
+type TransferClient = {
+    credentialSetups: Pick<CredentialSetupsApi, 'storeValue' | 'sourceResult' | 'get'>;
+};
+/** Onboarding opts in explicitly. The restricted machine agent never reads the source values. */
+export declare function credentialSetupAfterMachine(ctx: Ctx): Promise<void>;
+export declare function transferCredentialSetup(ctx: TransferContext, cloud: TransferClient, plan: CredentialSetup, options: CredentialDiscoveryOptions): Promise<CredentialSetup>;
+export declare const CREDENTIAL_SETUP_HANDLERS: Record<string, Handler>;
+export {};

package/dist/credential-setup.js

@@ -0,0 +1,181 @@
+/** Trusted local credential transfer. Models and stdout receive names, sources and status only. */
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { UsageError } from "./errors.js";
+import { captureLocalLoginEnvironment, discoverCredentialSources, readCredentialSource, CredentialSourceError } from "./credential-sources.js";
+const str = (value) => typeof value === 'string' ? value : undefined;
+function client(ctx) { return ctx.sessionSource() ? ctx.account() : ctx.cloud(); }
+/** Onboarding opts in explicitly. The restricted machine agent never reads the source values. */
+export async function credentialSetupAfterMachine(ctx) {
+    try {
+        const cloud = client(ctx);
+        if (!cloud.credentialSetups || !await cloud.credentialSetups.available())
+            return;
+        const quiet = { ...ctx, json: true, io: { ...ctx.io, stdout: { ...ctx.io.stdout, write: () => true } } };
+        await CREDENTIAL_SETUP_HANDLERS['credentials setup'](quiet, { 'from-this-computer': true, 'if-needed': true }, []);
+    }
+    catch {
+        ctx.io.stderr.write('Credential setup is pending. Continue with shard credentials setup --from-this-computer --if-needed.\n');
+    }
+}
+const itemResult = (item) => ({ id: item.id, name: item.name, state: item.state, scope: item.selected_scope, project_id: item.project_id, ...(item.delivery ? { delivery: item.delivery } : {}), ...(item.error_code ? { error_code: item.error_code } : {}) });
+function output(ctx, value) { if (ctx.json)
+    ctx.io.stdout.write(JSON.stringify(value) + '\n'); }
+export async function transferCredentialSetup(ctx, cloud, plan, options) {
+    if (plan.state === 'awaiting_approval')
+        return plan;
+    if (plan.state === 'denied' || plan.state === 'completed')
+        return plan;
+    const items = plan.items.filter(i => i.state === 'pending' && i.selected_scope !== null);
+    const transfer = async (item) => {
+        try {
+            const { project_id: sourceProject, ...descriptor } = item;
+            const candidate = { ...descriptor, ...(sourceProject ? { project_id: sourceProject } : {}), preferred: true };
+            const value = await readCredentialSource(candidate, options);
+            ctx.addWriteOnlyValue(value);
+            const stored = await cloud.credentialSetups.storeValue(plan.id, item.id, value);
+            const result = stored.items.find(i => i.id === item.id);
+            if (result)
+                output(ctx, { plan_id: plan.id, result: itemResult(result) });
+        }
+        catch (err) {
+            const code = err instanceof CredentialSourceError ? err.code : 'import_failed';
+            try {
+                const failed = await cloud.credentialSetups.sourceResult(plan.id, item.id, code);
+                const result = failed.items.find(i => i.id === item.id);
+                if (result)
+                    output(ctx, { plan_id: plan.id, result: itemResult(result) });
+            }
+            catch { /* Read authoritative status below; a lost write response may already have stored it. */ }
+        }
+    };
+    // Queue every approved source, while opening only a few vault readers/uploads together.
+    // Read the value inside the worker so queued credentials remain in their original source.
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(4, items.length) }, async () => {
+        for (;;) {
+            const item = items[next++];
+            if (!item)
+                return;
+            await transfer(item);
+        }
+    }));
+    return cloud.credentialSetups.get(plan.id, { signal: ctx.signal });
+}
+async function picks(ctx, path) {
+    let value;
+    if (path === '-') {
+        const chunks = [];
+        for await (const chunk of ctx.io.stdin)
+            chunks.push(Buffer.from(chunk));
+        value = Buffer.concat(chunks).toString('utf8');
+    }
+    else
+        value = await readFile(path, 'utf8');
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed) || !parsed.every((item) => {
+            if (!item || typeof item !== 'object' || Array.isArray(item))
+                return false;
+            const i = item;
+            return typeof i.id === 'string' && (i.scope === 'agents' || i.scope === 'project') && (i.project_id === undefined || typeof i.project_id === 'string') && Object.keys(i).every(k => ['id', 'scope', 'project_id'].includes(k));
+        }))
+            throw new Error();
+        return parsed;
+    }
+    catch {
+        throw new UsageError('--picks takes a JSON list of discovered source IDs and scopes.');
+    }
+}
+export const CREDENTIAL_SETUP_HANDLERS = {
+    async 'credentials setup'(ctx, values) {
+        const cloud = client(ctx), apply = str(values.apply), deny = str(values.deny), path = str(values.path);
+        if (!await cloud.credentialSetups.available())
+            throw new UsageError('Credential setup is being prepared. Update Shardflux and try again.');
+        if (apply && deny)
+            throw new UsageError('Choose --apply or --deny.');
+        if (deny) {
+            await cloud.needsYou.answer('csetup_' + deny, { decision: 'deny' });
+            output(ctx, { plan_id: deny, state: 'denied' });
+            if (!ctx.json)
+                ctx.io.stdout.write('Credential setup declined.\n');
+            return 0;
+        }
+        if (!apply && values['from-this-computer'] !== true)
+            throw new UsageError('Use --from-this-computer to bring your existing credentials along.');
+        let projectId = str(values.project) ?? ctx.store.profile(ctx.apiUrl).project_id, organizationId = ctx.store.profile(ctx.apiUrl).organization_id;
+        if (!projectId && !apply) {
+            try {
+                const me = await ctx.cloud().me();
+                if (!me.api_key)
+                    throw new UsageError('Select a project with --project.');
+                projectId = me.api_key.project_id;
+                organizationId ??= me.api_key.organization_id;
+            }
+            catch {
+                if (!ctx.sessionSource())
+                    throw new UsageError('Select a project with --project, or sign in first.');
+            }
+        }
+        const home = ctx.io.env.HOME ?? homedir();
+        const base = { home, env: ctx.io.env, ...(projectId ? { projectId, projectPath: path ?? process.cwd() } : {}), signal: ctx.signal };
+        const env = await captureLocalLoginEnvironment(base), options = { ...base, env };
+        let plan, prior = new Map();
+        if (apply) {
+            const selection = str(values.picks);
+            if (selection)
+                await cloud.needsYou.answer('csetup_' + apply, { credential_setup: { items: await picks(ctx, selection) } });
+            plan = await cloud.credentialSetups.get(apply, { signal: ctx.signal });
+        }
+        else {
+            const candidates = await discoverCredentialSources(options), localOnly = !ctx.sessionSource();
+            const normalized = (localOnly ? [...candidates].sort((a, b) => Number(b.suggested_scope === 'project') - Number(a.suggested_scope === 'project')) : candidates).map(c => ({ ...c, ...(localOnly ? { suggested_scope: 'project', project_id: projectId } : {}) }));
+            if (localOnly && !projectId)
+                throw new UsageError('Select a project with --project.');
+            const selected = new Set(), selectedItems = [];
+            for (const c of normalized)
+                if (c.preferred) {
+                    const key = JSON.stringify([c.suggested_scope, c.project_id, c.name]);
+                    if (!selected.has(key)) {
+                        selected.add(key);
+                        selectedItems.push(c.id);
+                    }
+                }
+            const items = normalized.map(({ id, name, source, suggested_scope, project_id }) => ({ id, name, source, suggested_scope, ...(project_id ? { project_id } : {}) }));
+            if (!items.length && values['if-needed'] === true) {
+                output(ctx, { needed: false, results: [] });
+                if (!ctx.json)
+                    ctx.io.stdout.write('No new credential sources found.\n');
+                return 0;
+            }
+            try {
+                const metadata = await cloud.secrets.listAgents({ ...organizationId ? { organizationId } : {} });
+                prior = new Map(metadata.map(s => [s.id, s.current_version]));
+            }
+            catch { /* An unavailable metadata read does not block the direct transfer. */ }
+            plan = await cloud.credentialSetups.create({ items, ...(projectId ? { projectId } : {}), ...(organizationId ? { organizationId } : {}), review: values.plan === true, ...(values.plan === true ? {} : { selectedItems }) });
+            if (!prior.size)
+                try {
+                    prior = new Map((await cloud.secrets.listAgents({ organizationId: plan.organization_id })).map(s => [s.id, s.current_version]));
+                }
+                catch { /* Transfers remain independent of this optional metadata read. */ }
+            output(ctx, { plan_id: plan.id, ...(values.plan === true ? { candidates: plan.items } : {}) });
+            if (values.plan === true) {
+                if (!ctx.json)
+                    ctx.io.stdout.write('Review the discovered names in Shard, then import the selected sources.\n');
+                return 0;
+            }
+        }
+        if (plan.state === 'awaiting_approval') {
+            output(ctx, { plan_id: plan.id, state: plan.state, results: plan.items.map(itemResult) });
+            return 0;
+        }
+        const final = await transferCredentialSetup(ctx, cloud, plan, options), failed = final.items.filter(i => i.state === 'failed').length, pending = final.items.filter(i => i.state === 'pending' || i.state === 'stored' && i.delivery?.state !== 'ready').length;
+        const stored = final.items.filter(i => i.state === 'stored'), needed = stored.some(i => !i.secret_id || prior.get(i.secret_id) !== i.secret_version);
+        const result = { plan_id: final.id, state: final.state, needed, results: final.items.map(itemResult), stored: stored.length, failed, pending };
+        output(ctx, result);
+        if (!ctx.json)
+            ctx.io.stdout.write(`${stored.length} credential${stored.length === 1 ? '' : 's'} stored${failed ? `, ${failed} source${failed === 1 ? '' : 's'} need attention` : ''}${pending ? `, ${pending} delivery pending` : ''}.\n`);
+        return failed ? 1 : 0;
+    },
+};

package/dist/credential-sources.d.ts

@@ -0,0 +1,34 @@
+export type CredentialSourceCode = 'source_unavailable' | 'source_changed' | 'source_not_text' | 'source_empty' | 'source_too_large' | 'source_has_nul' | 'vault_locked' | 'login_expired' | 'import_failed';
+export declare class CredentialSourceError extends Error {
+    readonly code: CredentialSourceCode;
+    constructor(code: CredentialSourceCode);
+}
+export interface CredentialCandidate {
+    id: string;
+    name: string;
+    source: {
+        kind: 'environment' | 'dotenv' | 'shell' | 'vault' | 'cli';
+        label: string;
+        reference: string;
+    };
+    suggested_scope: 'agents' | 'project';
+    project_id?: string;
+    preferred: boolean;
+}
+export interface CredentialDiscoveryOptions {
+    home: string;
+    env: Readonly<NodeJS.ProcessEnv>;
+    projectPath?: string;
+    projectId?: string;
+    signal?: AbortSignal;
+    /** Fixture-injected process boundary. stdout is private; stderr is never returned. */
+    run?: (argv: readonly string[], env: Readonly<NodeJS.ProcessEnv>, signal?: AbortSignal) => Promise<Buffer>;
+    /** Tests declare the fixture executables. Production resolves only the caller's PATH. */
+    availableCommands?: readonly string[];
+}
+export declare function credentialVariableName(name: string): boolean;
+/** Normal local login startup resolves exported vault expressions privately, without a model reading shell files. */
+export declare function captureLocalLoginEnvironment(options: CredentialDiscoveryOptions): Promise<NodeJS.ProcessEnv>;
+/** Reconstruct a source from metadata only, so a review can finish in a later CLI process. */
+export declare function readCredentialSource(candidate: CredentialCandidate, options: CredentialDiscoveryOptions): Promise<string>;
+export declare function discoverCredentialSources(options: CredentialDiscoveryOptions): Promise<CredentialCandidate[]>;