@shardflux/cli 0.28.1 → 0.28.3

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## 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).
+
+- Agent credentials (0.28.2+, SDK 0.30.2): environment credential questions can be answered with `shard needs-you answer acred_ID --credential --ask` (or stdin / `--from-file`), with scope chosen before the write. Scope flags preserve organization and thread identity; workspace-only permission flags are rejected for agent credentials.
+
+- Agent credential scopes (0.28.2+): `shard secrets create NAME --scope agents --org ORG --ask` adds a credential for all your agents; use `--scope project --project PROJECT` or `--scope conversation --conversation CONVERSATION` for a local override. Import, list, get, update, rotate, versions, access-log and delete accept the same scope. Values use the secure page, stdin, or `--from-file` and never command arguments.
+- Conversation origin (0.28.2+, SDK 0.30.2): conversation starts stay compatible with older APIs: send launching-conversation provenance only after `/v1/meta` advertises `capabilities.conversation_origin: true`; no create fallback retry.
+
+- Question explanations (0.28.2+, SDK 0.30.2): needs-you output prints each question and its optional `option_details` in full, including what each choice does and what follows it.
+
+- Launch attribution (0.28.2+, SDK 0.30.2): preserve the requesting orchestrator thread when `project_link` starts work in a laptop folder. API and guest title sources strip pasted-content/image transport markers, so `shard agents list` shows the request text. Tasks delete their workers and spawned descendants along with their computers.
+
 - The Shardflux app 0.9.2 (0.28.1+): `shard` installs and updates `@shardflux/desktop-darwin-arm64` / `-x64` and
   `@shardflux/desktop-linux-x64` / `-arm64` 0.9.2 (Stop in ⌘1, organization choice at the first sign-in, Sign in after
   signing out).

package/README.md

@@ -34,6 +34,12 @@ an explicit selection keeps the default credentials and target status. An approv
 
 Filesystem recovery timing (0.28.0+): cold resume output identifies `guest_filesystem` in JSON and the restart notice. See the [workspace lifecycle](https://docs.shardflux.dev/concepts/lifecycle) for retained files and process restart semantics.
 
+## Agent credentials (0.28.2+)
+
+Answer a credential question with `shard needs-you answer acred_ID --credential --ask --scope project`. The value goes to the write-only answer field and the asking agent receives an availability message.
+
+`shard secrets create NAME --scope agents --org ORG --ask` adds a credential for all your agents; use `--scope project --project PROJECT` or `--scope conversation --conversation CONVERSATION` for a local override. Import, list, get, update, rotate, versions, access-log and delete accept the same scope. Values use the secure page, stdin, or `--from-file` and never command arguments.
+
 ## Support and bug reports
 
 [Report a bug](https://github.com/shardfluxdev/community/issues/new?template=bug_report.yml) or
@@ -95,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.
 
@@ -257,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+):
 
@@ -1523,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
@@ -1635,6 +1646,8 @@ hour), and `--json` prints the API's answer. Pass an id to `shard agents new --m
 
 ## Conversations
 
+When an orchestrator starts work through a device project link (0.28.2+), the new conversation carries its requesting thread through to the API. `shard agents list --json` retains the orchestrator conversation and known input IDs.
+
 From 0.14.0, `shard conversations list|get|send|wait|land|move` manages project conversations. `shard c` is the short form. Conversations retain their branch and transcript as their VM binding changes.
 
 Watch an agent work: `shard conversations watch <id>` shows the conversation's terminal live, read-only. It starts
@@ -1907,7 +1920,7 @@ shard board --follow                               # each change as it happens,
 changes the words (`--text`, and the task's master hears it), the title (`--title`), the bucket (`--now`, `--next`,
 `--later`) and the order (`--first`, `--after`), keeps an agent's suggestion as your own (`--keep`) or clears the task
 (`--clear`; `--no-clear` brings it back). `shard task steer <id> <words...>` sends steering words to the task's master,
-`shard task rm <id>` deletes the task, and `shard task clear-done` clears every finished one. `shard task show <id>`
+`shard task rm <id>` deletes the task, every nested follow-up, and their owned conversation trees and computers; masters shared by other tasks stay. `shard task clear-done` clears every finished one. `shard task show <id>`
 prints the task, its plan and each report: milestone, outcome and evidence (`tests 12/12 (pnpm test)`).
 `shard task land <id>` lands a finished task: its result (the branch `shard/<task id>`, where its master merged its
 workers' branches) goes into the project's default branch and into your folder on this computer the way finished
@@ -2086,3 +2099,35 @@ shard volumes detach --machine datasets
 Defaults mount in new and running conversations. Removal waits for current work to finish and preserves manual attachments. Add `--json` to read propagation results.
 
 Bare `shard` in a coding-agent shell or without a TTY returns its setup guide using locally saved sign-in and API-key state.
+
+### Question explanations (0.28.2+)
+
+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.1";
+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.1';
+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).' },
@@ -127,6 +127,9 @@ const LIFETIME_FILTER = {
 };
 const SECRET_REF = { name: 'id|name', required: true };
 const SECRET_SCOPE = {
+    scope: { type: 'string', value: '<agents|project|conversation>', description: 'Agent credential scope: all your agents, this project, or one thread. Omit for workspace-bound secrets.' },
+    project: { type: 'string', value: '<project-id>', description: 'Project for a local agent credential (default: the key’s project).' },
+    conversation: { type: 'string', value: '<conversation-id>', description: 'Thread for --scope conversation.' },
     org: { type: 'string', value: '<organization-id>', description: 'Organization-wide secrets of this organization (owners/admins; project API keys get 403). Default: the API key’s project.' },
 };
 const SECRET_VALUE = {
@@ -241,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).' },
@@ -979,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: {} },
@@ -993,6 +1007,7 @@ const KEY_COMMANDS = [
         summary: 'Import named items from your vault as encrypted project secrets',
         positionals: [{ name: 'name', required: true, variadic: true }],
         options: {
+            ...SECRET_SCOPE,
             from: { type: 'string', value: '<hsec|1password|bitwarden|keychain>', description: 'Vault to read; values go straight into the encrypted secrets request.' },
             as: { type: 'string', value: '<secret-name>', description: 'Secret name for a single imported item.' },
             keychain: { type: 'string', value: '<path>', description: 'Read from this Keychain (keychain source only).' },

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),',
@@ -123,6 +124,12 @@ export const BOARD_COMMANDS = [
         summary: 'Answer something that waits on you (0.25.0+)',
         positionals: [{ name: 'id', required: true }, { name: 'decision' }],
         options: {
+            credential: { type: 'boolean', description: 'Provide an environment credential through the secure value input; never through --text.' },
+            scope: { type: 'string', value: '<agents|project|conversation>', description: 'Credential storage scope (default: what the request suggests).' },
+            org: { type: 'string', value: '<organization-id>', description: 'The organization for a signed-in credential answer.' },
+            ask: { type: 'boolean', description: 'Open the secure page for the credential value.' },
+            'from-file': { type: 'string', value: '<file>', description: 'Read the credential value from this file; never from an argument.' },
+            timeout: { type: 'string', value: '<duration>', description: 'How long the secure page waits (default 10m).' },
             everywhere: { type: 'boolean', description: 'With always: the rule covers every project.' },
             text: { type: 'string', value: '<answer>', description: 'Your answer to an agent’s question.' },
             pick: { type: 'string', multiple: true, value: '<option|question=option>', description: 'The option you pick for an agent’s question in a permission request (repeatable for a multi-select question; "<question>=<option>" when it asks several).' },
@@ -136,6 +143,7 @@ export const BOARD_COMMANDS = [
             '  ask_…     --text <answer>: the task’s master gets it',
             '  oq_…      --text <answer>: the orchestrator thread that asked gets it (0.27.0+)',
             '  cred_…    deny (the value goes through the credential request, sealed for its computer)',
+            '  acred_…   --credential --ask: provide an environment value securely, or deny to decline it',
             '  land_…    land (as shard task land: the result into your folder and the default branch), keep (the',
             '            branch stays) or discard',
             '  prune_…   --keep <task-id> for each task to keep, keep for all of them, or discard to clear them',

package/dist/board-commands.d.ts

@@ -44,7 +44,7 @@ export declare function feedJson(u: BoardUpdate): Record<string, unknown>;
 /** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. Every
  *  title, step and outcome prints whole (0.27.0+), however long the agent wrote it; the terminal wraps it. */
 export declare function taskDetailText(d: TaskDetail): string;
-/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, land_, prune_, dev_); undefined for another id. */
+/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, acred_, land_, prune_, dev_); undefined for another id. */
 export declare function itemKind(id: string): NeedsYouItem['kind'] | undefined;
 export interface AnswerInput {
     word?: string | undefined;

package/dist/board-commands.js

@@ -1,4 +1,6 @@
-import { out, principal, str, strs } from "./commands.js";
+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";
 import { NotFoundError, UsageError } from "./errors.js";
 import { time } from "./format.js";
@@ -36,8 +38,8 @@ export function taskLine(t) {
  * request your orchestrator made to your computer while it was offline reads "Waiting for your computer: list ~/code".
  */
 export function needsLine(n) {
-    const detail = n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.join(' / ') : n.land ? n.land.branch : n.device ? 'cancel drops it' : '';
-    return `${n.id}\t${oneLine(n.ask, 100)}${detail ? `\t${detail}` : ''}`;
+    const detail = n.credential?.kind === 'environment' ? [n.credential.name, n.credential.suggested_scope].filter(Boolean).join(' · ') : n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.map(o => n.option_details?.[o] ? `${o}: ${n.option_details[o]}` : o).join(' / ') : n.land ? n.land.branch : n.device ? 'cancel drops it' : '';
+    return `${n.id}\t${oneLine(n.ask, n.kind === 'question' || n.credential?.kind === 'environment' ? Infinity : 100)}${detail ? `\t${detail}` : ''}`;
 }
 /** A sealed report as --follow prints it: id, milestone, title, then its evidence labels. */
 export function reportLine(r) {
@@ -140,7 +142,7 @@ export function taskDetailText(d) {
             if (r.outcome.trim())
                 lines.push(`  ${whole(r.outcome)}`);
             if (r.options?.length)
-                lines.push(`  Options: ${r.options.join(' / ')}`);
+                lines.push(`  Options: ${r.options.map(o => r.option_details?.[o] ? `${o}: ${r.option_details[o]}` : o).join(' / ')}`);
             if (r.evidence.length)
                 lines.push(`  Evidence: ${r.evidence.map(evidenceText).join('; ')}`);
             if (r.media.length)
@@ -149,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. */
@@ -166,8 +170,8 @@ function orderOf(values) {
     return first ? null : after;
 }
 // ---- needs you -------------------------------------------------------------------------------
-const KINDS = { perm: 'permission', cq: 'question', ask: 'question', oq: 'question', cred: 'credential', land: 'land', prune: 'prune', dev: 'device' };
-/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, land_, prune_, dev_); undefined for another id. */
+const KINDS = { perm: 'permission', cq: 'question', ask: 'question', oq: 'question', cred: 'credential', acred: 'credential', land: 'land', prune: 'prune', dev: 'device' };
+/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, acred_, land_, prune_, dev_); undefined for another id. */
 export function itemKind(id) {
     return KINDS[id.slice(0, Math.max(0, id.indexOf('_')))];
 }
@@ -349,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;
     },
@@ -364,6 +368,45 @@ export const BOARD_HANDLERS = {
         return 0;
     },
     async 'needs-you answer'(ctx, values, [id, word]) {
+        if (values.credential === true) {
+            if (!id?.startsWith('acred_') || word !== undefined || values.text !== undefined || values.pick !== undefined || values.keep !== undefined || values.everywhere === true) {
+                throw new UsageError('Use --credential for an environment request, without a decision or chat answer.');
+            }
+            const hasKey = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+            const scope = str(values.scope);
+            if (scope !== undefined && !['agents', 'project', 'conversation'].includes(scope))
+                throw new UsageError('--scope must be agents, project or conversation');
+            const signed = scope === 'agents' || !hasKey;
+            let cloud = signed ? ctx.account() : ctx.cloud();
+            let organizationId = str(values.org);
+            if (signed) {
+                const org = organizationId ? await findOrg(ctx.account(), organizationId) : await resolveOrg(ctx, ctx.account(), {});
+                organizationId = org.id;
+            }
+            // Inspect the request before reading a file, stdin or opening the secure page.
+            const item = (await cloud.needsYou.list({ ...(organizationId ? { organizationId } : {}), signal: ctx.signal })).find(n => n.id === id);
+            if (!item || item.kind !== 'credential' || item.credential?.kind !== 'environment' || !item.credential.name)
+                throw new NotFoundError('Nothing waits for that environment credential.');
+            const target = scope ?? item.credential.suggested_scope ?? 'project';
+            if (target === 'agents' && !signed) {
+                organizationId ??= (await principal(ctx)).organization_id;
+                cloud = ctx.account();
+                await findOrg(ctx.account(), organizationId);
+            }
+            const save = (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);
+            const r = value !== null ? await save(value) : await askSecretValue(ctx, values, {
+                title: `Provide ${item.credential.name}`, purpose: item.credential.purpose ?? item.ask, name: item.credential.name,
+            }, save);
+            out(ctx, `Credential ${item.credential.name} is available (${target}).\n`, r);
+            return 0;
+        }
+        if (values.scope !== undefined || values.ask === true || values['from-file'] !== undefined || values.org !== undefined || values.timeout !== undefined) {
+            throw new UsageError('Use --credential for a secure environment credential answer.');
+        }
         const input = { word, text: str(values.text), picks: strs(values.pick), keep: strs(values.keep), everywhere: values.everywhere === true };
         const cloud = boardClient(ctx);
         // Land merges here (shard task land) and records itself after; the board only takes keep and discard.

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). */
@@ -152,4 +154,16 @@ export declare function withConversations(rows: import('@shardflux/sdk').Agent[]
     question?: string | null;
 }[] | null): ThreadRow[];
 export declare const KEY_HANDLERS: Record<string, Handler>;
+/**
+ * The secret value (never from arguments): --from-file, piped standard input, or a no-echo prompt on a terminal. Null
+ * when the person types it on the page shard opens instead (0.20.1+): --ask, or a coding agent's shell with nothing
+ * piped (a terminal there is not the person's).
+ */
+export declare function readSecretValue(ctx: Ctx, values: Values, name: string): Promise<string | null>;
+/** The secret's value from the page shard opens, handed straight to `save` (create or rotate); the page shows its outcome. */
+export declare function askSecretValue<T>(ctx: Ctx, values: Values, page: {
+    title: string;
+    purpose: string;
+    name: string;
+}, save: (value: string) => Promise<T>): Promise<T>;
 export {};

package/dist/commands.js

@@ -2345,17 +2345,20 @@ export const KEY_HANDLERS = {
         if (keychain && from !== 'keychain')
             throw new UsageError('--keychain applies to the keychain vault');
         const targets = secretNames(names.map(n => alias ?? n), '--as');
-        const project = (await principal(ctx)).project_id;
+        const agent = values.scope !== undefined ? await agentSecretContext(ctx, values) : null;
+        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(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;
     },
     async 'secrets create'(ctx, values, [name]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'create', name);
         if (!SECRET_NAME.test(name))
             throw new UsageError(`<name> must be an environment variable name like OPENAI_API_KEY (^[A-Z_][A-Z0-9_]*$), got "${name}"`);
         const scope = scopeFlag(values);
@@ -2377,6 +2380,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets list'(ctx, values) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'list', undefined);
         const cloud = ctx.cloud();
         const org = scopeFlag(values);
         const project = org === null ? (await principal(ctx)).project_id : null;
@@ -2404,11 +2409,15 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets get'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'get', ref);
         const s = await resolveSecret(ctx, values, ref);
         out(ctx, secretDetail(s), s);
         return 0;
     },
     async 'secrets update'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'update', ref);
         const s = await resolveSecret(ctx, values, ref);
         const params = { ...permissionParams(values, s.scope, 'update') };
         const description = str(values.description);
@@ -2421,6 +2430,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets rotate'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'rotate', ref);
         const value = await readSecretValue(ctx, values, ref);
         const s = await resolveSecret(ctx, values, ref);
         const rotate = (secret) => ctx.cloud().secrets.rotate(s.id, secret);
@@ -2433,6 +2444,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets versions'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'versions', ref);
         const s = await resolveSecret(ctx, values, ref);
         const limitText = str(values.limit);
         const page = await ctx.cloud().secrets.versions(s.id, limitText ? { limit: parsePositiveInt(limitText, 'limit', 200) } : {});
@@ -2440,6 +2453,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets delete'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'delete', ref);
         if (values.yes !== true)
             throw new UsageError('refusing to delete without --yes (the values are erased and the name is removed from every workspace binding)');
         const s = await resolveSecret(ctx, values, ref);
@@ -2448,6 +2463,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets access-log'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'access-log', ref);
         const outcome = str(values.outcome);
         if (outcome !== undefined && !['granted', 'denied', 'failed'].includes(outcome))
             throw new UsageError('--outcome must be granted, denied or failed');
@@ -2549,6 +2566,106 @@ function updateLine(u, d) {
     }
 }
 /** `--org <id>`: organization scope; null: the API key's project. */
+async function agentSecretContext(ctx, values) {
+    const scope = str(values.scope);
+    if (!['agents', 'project', 'conversation'].includes(scope ?? ''))
+        throw new UsageError('--scope must be agents, project or conversation');
+    const restrictions = ['tool', 'allow-workspace', 'any-workspace', 'allow-project', 'all-projects', 'clear-projects'];
+    if (restrictions.some(k => Array.isArray(values[k]) ? values[k].length > 0 : values[k] !== undefined && values[k] !== false))
+        throw new UsageError('Workspace tool permissions apply to workspace-bound secrets. Agent credentials use their agents, project or conversation scope.');
+    if (scope === 'agents' && (values.project !== undefined || values.conversation !== undefined))
+        throw new UsageError('--scope agents takes --org; use a local scope for --project or --conversation.');
+    if (scope === 'project' && values.conversation !== undefined)
+        throw new UsageError('Use --scope conversation with --conversation.');
+    const hasKey = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+    const cloud = scope === 'agents' || !hasKey ? ctx.account() : ctx.cloud();
+    if (scope === 'agents') {
+        const account = ctx.account(), org = str(values.org);
+        const organization = org ? await findOrg(account, org) : await resolveOrg(ctx, account, {});
+        return { cloud, target: { scope, organizationId: organization.id } };
+    }
+    const localOrg = str(values.org);
+    if (localOrg !== undefined && !UUID.test(localOrg))
+        throw new UsageError('--org must be an organization id for a local credential.');
+    const organization = localOrg ? { organizationId: localOrg } : {};
+    if (scope === 'conversation') {
+        const conversationId = str(values.conversation);
+        if (!conversationId)
+            throw new UsageError('--conversation is required with --scope conversation');
+        return { cloud, target: { scope, conversationId, ...organization, ...(str(values.project) ? { projectId: str(values.project) } : {}) } };
+    }
+    const projectId = str(values.project) ?? (hasKey ? (await principal(ctx)).project_id : undefined);
+    if (!projectId)
+        throw new UsageError('--project is required with a signed-in session and --scope project');
+    return { cloud, target: { scope: 'project', projectId, ...organization } };
+}
+async function agentSecretCommand(ctx, values, action, ref) {
+    const { cloud, target } = await agentSecretContext(ctx, values);
+    if (action === 'list' && (values.limit !== undefined || values.cursor !== undefined || values['include-deleted'] === true))
+        throw new UsageError('Agent credential lists return all active names. Pagination and deleted-history flags apply to workspace-bound secrets.');
+    const describe = (r) => `${r.name} (${r.id}) · ${r.scope} · version ${r.current_version}\n`;
+    if (action === 'list') {
+        const data = await cloud.secrets.listAgents(target);
+        out(ctx, data.map(describe).join('') || 'No credentials.\n', { data });
+        return 0;
+    }
+    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.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;
+    }
+    const r = UUID.test(ref ?? '') ? await cloud.secrets.getAgent(ref) : (await cloud.secrets.listAgents(target)).find(r => r.name === ref);
+    if (!r)
+        throw new NotFoundError(`No credential named ${ref} in this scope.`);
+    // An id is still checked against the explicitly named target rather than silently operating in another scope.
+    if (r.scope !== target.scope || target.organizationId && r.organization_id !== target.organizationId || target.projectId && r.project_id !== target.projectId || target.conversationId && r.conversation_id !== target.conversationId)
+        throw new NotFoundError('That credential belongs to another scope.');
+    if (action === 'get') {
+        out(ctx, describe(r), r);
+        return 0;
+    }
+    if (action === 'update') {
+        const description = str(values.description);
+        if (description === undefined)
+            throw new UsageError('Pass --description to update an agent credential.');
+        const changed = await cloud.secrets.updateAgent(r.id, description);
+        out(ctx, describe(changed), changed);
+        return 0;
+    }
+    if (action === 'rotate') {
+        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;
+    }
+    if (action === 'delete') {
+        if (values.yes !== true)
+            throw new UsageError('Pass --yes to erase this credential.');
+        await cloud.secrets.deleteAgent(r.id);
+        out(ctx, `Deleted ${r.name}.\n`, { deleted: true, id: r.id, name: r.name, scope: r.scope });
+        return 0;
+    }
+    if (action === 'versions') {
+        const limit = str(values.limit);
+        const page = await cloud.secrets.versions(r.id, limit ? { limit: parsePositiveInt(limit, 'limit', 200) } : {});
+        out(ctx, secretVersionTable(page.data), { data: page.data, next_cursor: page.nextCursor });
+        return 0;
+    }
+    if (action === 'access-log') {
+        const outcome = str(values.outcome), workspace = str(values.workspace), limit = str(values.limit);
+        if (outcome !== undefined && !['granted', 'denied', 'failed'].includes(outcome))
+            throw new UsageError('--outcome must be granted, denied or failed');
+        if (workspace !== undefined && !UUID.test(workspace))
+            throw new UsageError('--workspace must be a workspace id');
+        const page = await cloud.secrets.accessEvents(r.id, { ...(outcome ? { outcome: outcome } : {}), ...(workspace ? { workspaceId: workspace } : {}), ...(limit ? { limit: parsePositiveInt(limit, 'limit', 200) } : {}) });
+        out(ctx, JSON.stringify(page.data) + '\n', { data: page.data, next_cursor: page.nextCursor });
+        return 0;
+    }
+    throw new UsageError('Unknown credential action.');
+}
 function scopeFlag(values) {
     const org = str(values.org);
     if (org === undefined)
@@ -2599,7 +2716,7 @@ function permissionParams(values, scope, mode) {
  * when the person types it on the page shard opens instead (0.20.1+): --ask, or a coding agent's shell with nothing
  * piped (a terminal there is not the person's).
  */
-async function readSecretValue(ctx, values, name) {
+export async function readSecretValue(ctx, values, name) {
     const file = str(values['from-file']);
     if (values.ask === true) {
         if (file !== undefined)
@@ -2643,7 +2760,7 @@ function secretText(value) {
     return text;
 }
 /** The secret's value from the page shard opens, handed straight to `save` (create or rotate); the page shows its outcome. */
-async function askSecretValue(ctx, values, page, save) {
+export async function askSecretValue(ctx, values, page, save) {
     const asked = await askInBrowser(ctx, {
         kind: 'secret',
         title: page.title,

package/dist/conversations.d.ts

@@ -59,6 +59,8 @@ export interface Conversation {
     started_by?: {
         user_id: string;
     } | null;
+    orchestrator_conversation_id?: string | null;
+    orchestrator_input_id?: string | null;
 }
 export interface LocalConversation {
     api_url: string;

package/dist/conversations.js

@@ -250,7 +250,7 @@ export async function createConversationRecord(ctx, folder, harness, route, name
     capture.catch(() => undefined);
     // The title marker this computer chose (`shard settings --title-prefix`, 0.20.1+); none sent means the platform's.
     const titlePrefix = storedTitlePrefix(ctx.store.dir);
-    const response = await conversationClient(ctx).conversations.create({ repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
+    const response = await conversationClient(ctx).conversations.create({ fromConversationId: ctx.io.env.SF_CONVERSATION_ID, repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
         base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), ...choice, projectId: ctx.store.profile(ctx.apiUrl).project_id,
         ...(titlePrefix !== undefined ? { titlePrefix } : {}),
         ...(movedIn ? { harnessSessionId: movedIn.session_id, ...(movedIn.title ? { title: movedIn.title.slice(0, 200) } : {}) } : {}) }, { idempotencyKey, signal: ctx.signal });

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