@shardflux/cli 0.28.2 → 0.28.3

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+- 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

@@ -101,7 +101,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 +263,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 +1532,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
@@ -2100,3 +2105,29 @@ 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+)
+
+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.

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.28.2";
+export declare const CLI_VERSION = "0.28.3";
 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.3';
 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/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,13 @@
+import type { CredentialSetup, CredentialSetupsApi, SecretsApi, NeedsYouApi } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+import type { CredentialDiscoveryOptions } from './credential-sources.js';
+interface SetupClient {
+    credentialSetups: CredentialSetupsApi;
+    secrets: SecretsApi;
+    needsYou: NeedsYouApi;
+}
+/** 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: Ctx, cloud: SetupClient, plan: CredentialSetup, options: CredentialDiscoveryOptions): Promise<CredentialSetup>;
+export declare const CREDENTIAL_SETUP_HANDLERS: Record<string, Handler>;
+export {};

package/dist/credential-setup.js

@@ -0,0 +1,170 @@
+/** 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 jobs = plan.items.filter(i => i.state === 'pending' && i.selected_scope !== null).map(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. */ }
+        }
+    });
+    await Promise.allSettled(jobs);
+    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[]>;