@shardflux/cli 0.28.2 → 0.28.4

package/dist/credential-sources.js

@@ -0,0 +1,400 @@
+/** Source discovery exposes descriptors only. Values stay in this process and go directly to the write-only API. */
+import { randomUUID } from 'node:crypto';
+import { readFile, readdir, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+import { parseEnv } from 'node:util';
+import { spawn } from 'node:child_process';
+import { parse as parseYaml } from 'yaml';
+import { vaultValue } from "./vault.js";
+export class CredentialSourceError extends Error {
+    code;
+    constructor(code) { super('The credential source could not be read.'); this.code = code; }
+}
+const SYSTEM_NAMES = new Set(['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LANGUAGE', 'LC_ALL', 'TERM', 'COLORTERM', 'PWD', 'OLDPWD', 'SHLVL', '_', 'TMPDIR', 'TMP', 'TEMP', 'XDG_RUNTIME_DIR', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME', 'XDG_DATA_HOME', 'SSH_AUTH_SOCK', 'SSH_AGENT_PID', 'DISPLAY', 'EDITOR', 'VISUAL', 'PAGER', 'MANPAGER', 'LESS', 'LSCOLORS', 'LS_COLORS', 'TERM_PROGRAM', 'TERM_PROGRAM_VERSION', 'TERM_SESSION_ID', 'VIRTUAL_ENV', 'CONDA_PREFIX', 'CONDA_DEFAULT_ENV', 'CONDA_SHLVL', 'JAVA_HOME', 'GOPATH', 'GOROOT', 'GOCACHE', 'GOMODCACHE', 'RUSTUP_HOME', 'CARGO_HOME', 'NODE_PATH', 'NODE_OPTIONS', 'BASH_ENV', 'ENV', 'SHELLOPTS', 'BASHOPTS', 'LD_PRELOAD', 'LD_LIBRARY_PATH', 'SHARD_DEVICE_HELPER']);
+for (const name of ['BW_SESSION', 'BW_PASSWORD', 'BW_CLIENTSECRET', 'OP_SERVICE_ACCOUNT_TOKEN', 'OP_CONNECT_TOKEN', 'NODE_ENV', 'SF_CONVERSATION_ID', 'SF_PROJECT_ID', 'SF_WORKSPACE_ID', 'SF_ORGANIZATION_ID', 'SF_AGENT_LABEL', 'SF_HARNESS_SESSION_ID', 'SF_ACTOR', 'SF_ENV'])
+    SYSTEM_NAMES.add(name);
+// Same owned launcher controls as API agent-names and guest agentenv.ValidName.
+for (const name of ['SF_PROJECT_NAME', 'SF_REPO_NAME', 'SF_ACP_MODEL_DISCOVERY', 'SF_DESKTOP_SOCKET', 'SF_PTY_SESSION_ID', 'SF_SESSION_PLACE', 'SF_SESSION_TITLE', 'SF_SESSION_TITLE_PREFIX', 'SF_SESSION_TITLE_FROM_PROMPT', 'SF_TASK_TITLE', 'SF_LOGIN_ENV', 'CODEX_HOME', 'CLAUDE_CONFIG_DIR', 'CLAUDE_CODE_ENABLE_TELEMETRY', 'DISABLE_TELEMETRY', 'DISABLE_ERROR_REPORTING'])
+    SYSTEM_NAMES.add(name);
+export function credentialVariableName(name) { return /^[A-Z_][A-Z0-9_]{0,127}$/.test(name) && !name.startsWith('SF_AGENT_') && !name.startsWith('SHARDFLUX_') && !name.startsWith('OP_SESSION_') && !name.startsWith('LC_') && !SYSTEM_NAMES.has(name); }
+function checked(value) {
+    if (value === undefined)
+        throw new CredentialSourceError('source_changed');
+    if (!value.length)
+        throw new CredentialSourceError('source_empty');
+    if (value.includes('\0'))
+        throw new CredentialSourceError('source_has_nul');
+    if (Buffer.byteLength(value) > 65536)
+        throw new CredentialSourceError('source_too_large');
+    return value;
+}
+async function text(path) {
+    let bytes;
+    try {
+        bytes = await readFile(path);
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        bytes?.fill(0);
+    }
+}
+function shellAssignments(source) {
+    const result = new Map();
+    // Parse assignment syntax; never source/evaluate a shell file or hand it to a model.
+    let through = 0;
+    for (const m of source.matchAll(/^[ \t]*(?:export[ \t]+)?([A-Z_][A-Z0-9_]*)=/gm)) {
+        if (m.index < through)
+            continue;
+        const start = m.index + m[0].length;
+        let i = start, quote = '';
+        for (; i < source.length; i++) {
+            const c = source[i];
+            if (c === '\\' && quote !== "'") {
+                i++;
+                continue;
+            }
+            if (c === quote) {
+                quote = '';
+                continue;
+            }
+            if (!quote && (c === "'" || c === '"')) {
+                quote = c;
+                continue;
+            }
+            if (!quote && (c === '\n' || c === '#' && i > start && /\s/.test(source[i - 1])))
+                break;
+        }
+        result.set(m[1], source.slice(start, i));
+        through = i;
+    }
+    return result;
+}
+function shellLiteral(expression, env) {
+    let value = '', quote = '';
+    for (let i = 0; i < expression.length; i++) {
+        const c = expression[i];
+        if (c === '\\' && quote !== "'") {
+            const next = expression[++i];
+            if (next === undefined)
+                throw new CredentialSourceError('source_unavailable');
+            if (quote === '"' && !['$', '`', '"', '\\', '\n'].includes(next))
+                value += '\\';
+            if (next !== '\n')
+                value += next;
+            continue;
+        }
+        if (c === quote) {
+            quote = '';
+            continue;
+        }
+        if ((c === "'" || c === '"') && !quote) {
+            quote = c;
+            continue;
+        }
+        if (!quote && /\s/.test(c)) {
+            const tail = expression.slice(i).trim();
+            if (!tail || tail.startsWith('#'))
+                return checked(value);
+            throw new CredentialSourceError('source_unavailable');
+        }
+        if (quote !== "'" && c === '`' || !quote && [';', '|', '&', '<', '>', '(', ')'].includes(c))
+            throw new CredentialSourceError('source_unavailable');
+        if (quote !== "'" && c === '$') {
+            const m = /^\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/.exec(expression.slice(i));
+            if (!m)
+                throw new CredentialSourceError('source_unavailable');
+            const name = m[1] ?? m[2];
+            if (env[name] === undefined)
+                throw new CredentialSourceError('source_unavailable');
+            value += env[name];
+            i += m[0].length - 1;
+            continue;
+        }
+        value += c;
+    }
+    if (quote)
+        throw new CredentialSourceError('source_unavailable');
+    return checked(value);
+}
+function vaultExpression(expression) {
+    const raw = expression.trim().replace(/^"(.*)"$/, '$1');
+    let m = /^\$\(hsec get ([A-Za-z0-9_./:@+-]+)\)$/.exec(raw);
+    if (m)
+        return { vault: 'hsec', reference: m[1] };
+    m = /^\$\(op read (op:\/\/[^\s;|&`$]+)\)$/.exec(raw);
+    if (m)
+        return { vault: '1password', reference: m[1] };
+    m = /^\$\(bw get password ([A-Za-z0-9_./:@+-]+)\)$/.exec(raw);
+    if (m)
+        return { vault: 'bitwarden', reference: m[1] };
+    return null;
+}
+function ini(source) {
+    const sections = new Map();
+    let section = 'default';
+    for (const line of source.split(/\r?\n/)) {
+        const group = /^\s*\[([^\]]+)\]\s*$/.exec(line);
+        if (group) {
+            section = group[1].replace(/^profile /, '');
+            continue;
+        }
+        const pair = /^\s*([^=;#\s]+)\s*=\s*(.*?)\s*$/.exec(line);
+        if (!pair)
+            continue;
+        if (!sections.has(section))
+            sections.set(section, {});
+        sections.get(section)[pair[1]] = pair[2];
+    }
+    return sections;
+}
+async function privateRun(argv, env, signal) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        const child = spawn(argv[0], argv.slice(1), { env, signal, stdio: ['ignore', 'pipe', 'ignore'] });
+        child.stdout.on('data', (b) => chunks.push(b));
+        const wipe = () => { for (const b of chunks)
+            b.fill(0); };
+        child.once('error', () => { wipe(); reject(new CredentialSourceError('source_unavailable')); });
+        child.once('close', code => { if (code !== 0) {
+            wipe();
+            reject(new CredentialSourceError('login_expired'));
+        }
+        else {
+            const b = Buffer.concat(chunks);
+            wipe();
+            resolve(b);
+        } });
+    });
+}
+async function hasCommand(command, options) {
+    if (options.availableCommands)
+        return options.availableCommands.includes(command);
+    for (const folder of (options.env.PATH ?? '').split(':').filter(Boolean))
+        try {
+            await access(join(folder, command), constants.X_OK);
+            return true;
+        }
+        catch { /* next PATH entry */ }
+    return false;
+}
+/** Vault output stays private. Only item names/IDs become candidate descriptors. */
+async function vaultCandidates(options) {
+    const result = [], run = options.run ?? privateRun;
+    for (const command of ['hsec', 'op', 'bw', 'security']) {
+        if (!await hasCommand(command, options))
+            continue;
+        const argv = command === 'hsec' ? ['hsec', 'ls'] : command === 'op' ? ['op', 'item', 'list', '--format', 'json'] : command === 'bw' ? ['bw', 'list', 'items'] : ['security', 'dump-keychain'];
+        let bytes;
+        try {
+            bytes = await run(argv, options.env, options.signal);
+            const source = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            if (command === 'hsec')
+                for (const name of source.split(/\r?\n/).map(n => n.trim())) {
+                    if (credentialVariableName(name))
+                        result.push({ name, vault: 'hsec', item: name, label: 'hsec' });
+                }
+            else if (command === 'security')
+                for (const match of source.matchAll(/"svce"<blob>="([A-Z_][A-Z0-9_]*)"/g)) {
+                    const name = match[1];
+                    if (credentialVariableName(name))
+                        result.push({ name, vault: 'keychain', item: name, label: 'Keychain' });
+                }
+            else {
+                const items = JSON.parse(source);
+                if (!Array.isArray(items))
+                    continue;
+                for (const raw of items) {
+                    if (!raw || typeof raw !== 'object')
+                        continue;
+                    const item = raw;
+                    const name = command === 'op' ? item.title : item.name;
+                    if (typeof name !== 'string' || !credentialVariableName(name) || typeof item.id !== 'string' || !item.id || item.id.startsWith('-') || item.id.includes('\0') || item.deletedDate)
+                        continue;
+                    result.push({ name, vault: command === 'op' ? '1password' : 'bitwarden', item: item.id, label: command === 'op' ? '1Password' : 'Bitwarden' });
+                }
+            }
+        }
+        catch { /* A locked or unavailable vault does not block the other existing sources. */ }
+        finally {
+            bytes?.fill(0);
+        }
+    }
+    return result;
+}
+/** Normal local login startup resolves exported vault expressions privately, without a model reading shell files. */
+export async function captureLocalLoginEnvironment(options) {
+    const shell = options.env.SHELL;
+    if (!shell?.startsWith('/'))
+        return { ...options.env };
+    const marker = '\0SHARDFLUX_CREDENTIAL_ENV_START\0';
+    let bytes;
+    try {
+        bytes = await (options.run ?? privateRun)([shell, '-ilc', "printf '\\0SHARDFLUX_CREDENTIAL_ENV_START\\0'; /usr/bin/env -0"], { ...options.env, HOME: options.home }, options.signal);
+        const start = bytes.indexOf(Buffer.from(marker));
+        if (start < 0)
+            return { ...options.env };
+        const env = { ...options.env };
+        for (const entry of new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(start + Buffer.byteLength(marker))).split('\0')) {
+            const equal = entry.indexOf('=');
+            if (equal > 0)
+                env[entry.slice(0, equal)] = entry.slice(equal + 1);
+        }
+        return env;
+    }
+    catch {
+        return { ...options.env };
+    }
+    finally {
+        bytes?.fill(0);
+    }
+}
+/** Reconstruct a source from metadata only, so a review can finish in a later CLI process. */
+export async function readCredentialSource(candidate, options) {
+    const { source, name } = candidate;
+    try {
+        if (source.kind === 'environment')
+            return checked(options.env[source.reference]);
+        if (source.kind === 'dotenv') {
+            const file = await text(source.reference);
+            if (file === undefined)
+                throw new CredentialSourceError('source_unavailable');
+            return checked(parseEnv(file)[name]);
+        }
+        if (source.kind === 'shell') {
+            const file = await text(source.reference);
+            if (file === undefined)
+                throw new CredentialSourceError('source_unavailable');
+            const expression = shellAssignments(file).get(name);
+            if (expression === undefined)
+                throw new CredentialSourceError('source_changed');
+            return shellLiteral(expression, options.env);
+        }
+        const ref = JSON.parse(source.reference);
+        if (source.kind === 'vault') {
+            if (!ref.vault || !ref.item)
+                throw new CredentialSourceError('source_unavailable');
+            try {
+                return checked(await vaultValue(ref.vault, ref.item, { env: options.env, signal: options.signal }));
+            }
+            catch {
+                throw new CredentialSourceError('vault_locked');
+            }
+        }
+        if (ref.kind === 'aws-file') {
+            if (!ref.path || !ref.profile || !ref.field)
+                throw new CredentialSourceError('source_unavailable');
+            const file = await text(ref.path);
+            if (file === undefined)
+                throw new CredentialSourceError('source_unavailable');
+            return checked(ini(file).get(ref.profile)?.[ref.field]);
+        }
+        const run = options.run ?? privateRun;
+        if (ref.kind === 'aws' && ref.profile && ref.field) {
+            const bytes = await run(['aws', 'configure', 'export-credentials', '--profile', ref.profile, '--format', 'process'], options.env, options.signal);
+            try {
+                const data = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+                return checked(data[ref.field]);
+            }
+            finally {
+                bytes.fill(0);
+            }
+        }
+        if (ref.kind === 'gh' && ref.host) {
+            const bytes = await run(['gh', 'auth', 'token', '--hostname', ref.host], options.env, options.signal);
+            try {
+                return checked(new TextDecoder('utf-8', { fatal: true }).decode(bytes).replace(/\r?\n$/, ''));
+            }
+            finally {
+                bytes.fill(0);
+            }
+        }
+        throw new CredentialSourceError('source_unavailable');
+    }
+    catch (err) {
+        if (err instanceof CredentialSourceError)
+            throw err;
+        throw new CredentialSourceError('source_not_text');
+    }
+}
+export async function discoverCredentialSources(options) {
+    const found = [];
+    const add = (name, kind, label, reference, scope, preferred = true) => {
+        if (!credentialVariableName(name))
+            return;
+        found.push({ id: randomUUID(), name, source: { kind, label, reference }, suggested_scope: scope, ...(scope === 'project' && options.projectId ? { project_id: options.projectId } : {}), preferred });
+    };
+    for (const name of Object.keys(options.env).sort())
+        if (options.env[name] !== undefined)
+            add(name, 'environment', 'Current shell', name, 'agents');
+    for (const filename of ['.zshenv', '.zprofile', '.zshrc', '.bash_profile', '.bash_login', '.profile', '.bashrc']) {
+        const path = join(options.home, filename), source = await text(path);
+        if (source === undefined)
+            continue;
+        for (const [name, expression] of shellAssignments(source)) {
+            const vault = vaultExpression(expression);
+            if (vault)
+                add(name, 'vault', '~/' + filename + ' · ' + vault.vault, JSON.stringify({ vault: vault.vault, item: vault.reference }), 'agents', options.env[name] === undefined);
+            else
+                add(name, 'shell', '~/' + filename, path, 'agents', options.env[name] === undefined);
+        }
+    }
+    if (options.projectPath) {
+        let names = [];
+        try {
+            names = await readdir(options.projectPath);
+        }
+        catch { /* a missing folder has no files */ }
+        const examples = new Set(['.env.example', '.env.sample', '.env.template', '.env.defaults', '.env.dist']);
+        const mode = options.env.NODE_ENV, priority = mode ? [`.env.${mode}.local`, '.env.local', `.env.${mode}`, '.env'] : ['.env.local', '.env'];
+        const rank = (name) => priority.includes(name) ? priority.indexOf(name) : priority.length;
+        for (const filename of names.sort((a, b) => rank(a) - rank(b) || a.localeCompare(b)))
+            if (filename.startsWith('.env') && !examples.has(filename)) {
+                const path = join(options.projectPath, filename), source = await text(path);
+                if (source === undefined)
+                    continue;
+                for (const name of Object.keys(parseEnv(source)))
+                    add(name, 'dotenv', filename, path, 'project');
+            }
+    }
+    const awsFile = join(options.home, '.aws/credentials'), credentials = await text(awsFile), config = await text(join(options.home, '.aws/config'));
+    const profiles = new Map();
+    for (const [name, fields] of ini(credentials ?? ''))
+        profiles.set(name, fields);
+    for (const [name] of ini(config ?? ''))
+        if (!name.startsWith('sso-session ') && !profiles.has(name))
+            profiles.set(name, {});
+    const active = options.env.AWS_PROFILE ?? options.env.AWS_DEFAULT_PROFILE ?? 'default';
+    const fields = [['AWS_ACCESS_KEY_ID', 'aws_access_key_id', 'AccessKeyId'], ['AWS_SECRET_ACCESS_KEY', 'aws_secret_access_key', 'SecretAccessKey'], ['AWS_SESSION_TOKEN', 'aws_session_token', 'SessionToken']];
+    for (const [profile, values] of profiles)
+        for (const [name, field, apiField] of fields) {
+            if (Object.keys(values).length && !values[field])
+                continue;
+            add(name, 'cli', 'AWS profile ' + profile, JSON.stringify(values[field] ? { kind: 'aws-file', path: awsFile, profile, field } : { kind: 'aws', profile, field: apiField }), 'agents', profile === active && options.env[name] === undefined);
+        }
+    const hosts = await text(join(options.home, '.config/gh/hosts.yml'));
+    if (hosts) {
+        try {
+            const data = parseYaml(hosts);
+            if (data && typeof data === 'object')
+                for (const host of Object.keys(data))
+                    add('GH_TOKEN', 'cli', 'GitHub login · ' + host, JSON.stringify({ kind: 'gh', host }), 'agents', host === (options.env.GH_HOST ?? 'github.com') && options.env.GH_TOKEN === undefined);
+        }
+        catch { /* unreadable login metadata is not sent to a model or report */ }
+    }
+    for (const item of await vaultCandidates(options))
+        add(item.name, 'vault', item.label, JSON.stringify({ vault: item.vault, item: item.item }), 'agents', options.env[item.name] === undefined);
+    // Ordinary defaults use the first preferred source per logical name/scope. Every alternative remains reviewable.
+    const chosen = new Set();
+    for (const candidate of found) {
+        const key = JSON.stringify([candidate.suggested_scope, candidate.project_id, candidate.name]);
+        if (candidate.preferred && chosen.has(key))
+            candidate.preferred = false;
+        if (candidate.preferred)
+            chosen.add(key);
+    }
+    return found;
+}

package/dist/device-bridge.d.ts

@@ -10,7 +10,7 @@ export interface DeviceRequest {
     conversation_id: string;
     state: string;
     device_id: string | null;
-    kind: 'exec' | 'files_pull' | 'files_push' | 'port_forward' | 'port_reverse' | 'try_locally' | 'dir_list' | 'project_link';
+    kind: 'exec' | 'files_pull' | 'files_push' | 'port_forward' | 'port_reverse' | 'try_locally' | 'dir_list' | 'project_link' | 'credentials_setup';
     exec?: {
         argv: string[];
         cwd_relative?: string;
@@ -36,6 +36,10 @@ export interface DeviceRequest {
         brief?: string;
         harness?: 'claude' | 'codex';
     };
+    credentials?: {
+        path?: string;
+        names?: string[];
+    };
 }
 export interface DeviceApproval {
     type: 'approval';
@@ -72,6 +76,9 @@ export interface DeviceApproval {
     choose_mode?: true;
 }
 export type Result = {
+    credential_setup?: {
+        plan_id: string;
+    };
     state: 'approved' | 'denied' | 'running' | 'done' | 'failed';
     exit_code?: number;
     stdout_b64?: string;

package/dist/device-bridge.js

@@ -1,3 +1,5 @@
+import { captureLocalLoginEnvironment, discoverCredentialSources } from "./credential-sources.js";
+import { transferCredentialSetup } from "./credential-setup.js";
 import { createHash } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync } from 'node:fs';
@@ -17,7 +19,7 @@ import { checkConversationWorktree, rememberConversationWorktree } from "./conve
 import { yourComputer } from "./this-computer.js";
 import { canonicalDevicePath, deviceHome, displayPath, expandDevicePath, FOLDER_KINDS, isDevicePath, linkLocalProject, listDeviceDir } from "./device-folders.js";
 import { ownConversation } from "./agent-config-return.js";
-import { deviceApprovalMode, recordDeviceActivity, runsWithoutAsking } from "./device-mode.js";
+import { deviceApprovalMode, recordDeviceActivity, recordDeviceResult, runsWithoutAsking } from "./device-mode.js";
 import { setTimeout as delay } from 'node:timers/promises';
 /**
  * Posts a request's answer. An API before a linked folder's start point (train 47) refuses a link's commit and branch
@@ -247,7 +249,7 @@ export class DeviceExecutor {
         const auto = this.#auto.get(r.id);
         if (auto && result.state !== 'approved' && result.state !== 'running') {
             this.#auto.delete(r.id);
-            recordDeviceActivity(this.#ctx.store.dir, { ...auto, at: new Date().toISOString(), state: result.state, ...(result.exit_code !== undefined ? { exit_code: result.exit_code } : {}) });
+            recordDeviceResult(this.#ctx.store.dir, auto, { ...result, state: result.state });
         }
         await conversationClient(this.#ctx).deviceRequests.result(safeId(r.id), result, { idempotencyKey: `${this.#deviceId}:${r.id}:${result.state}${again}`, signal: this.#ctx.signal });
     }
@@ -310,11 +312,52 @@ export class DeviceExecutor {
             await watch;
         }
     }
+    async #credentials(r) {
+        const ctx = this.#ctx, c = await getConversation(ctx, r.conversation_id), records = localConversations(ctx);
+        if (c.project_id !== r.project_id || !ownConversation(c, records, await this.#me()) || archived(c)) {
+            await this.result(r, { state: 'denied' });
+            return;
+        }
+        await this.result(r, { state: 'approved' });
+        try {
+            const matching = Object.values(records).filter(record => record.project_id === r.project_id), folders = new Set(matching.map(record => record.folder));
+            const folder = r.credentials?.path ? expandDevicePath(r.credentials.path, deviceHome(ctx)) : records[r.conversation_id]?.folder ?? (folders.size === 1 ? matching[0]?.folder : undefined);
+            const base = { home: deviceHome(ctx), env: ctx.io.env, projectId: r.project_id, ...(folder ? { projectPath: folder } : {}), signal: ctx.signal };
+            const env = await captureLocalLoginEnvironment(base), options = { ...base, env };
+            const requested = r.credentials?.names ? new Set(r.credentials.names) : null;
+            let sources = (await discoverCredentialSources(options)).filter(source => !requested || requested.has(source.name));
+            const cloud = ctx.sessionSource() ? ctx.account() : conversationClient(ctx);
+            if (!ctx.sessionSource())
+                sources = [...sources].sort((a, b) => Number(b.suggested_scope === 'project') - Number(a.suggested_scope === 'project')).map(source => ({ ...source, suggested_scope: 'project', project_id: r.project_id }));
+            const selected = new Set(), ids = [];
+            for (const source of sources)
+                if (source.preferred) {
+                    const target = JSON.stringify([source.suggested_scope, source.project_id, source.name]);
+                    if (!selected.has(target)) {
+                        selected.add(target);
+                        ids.push(source.id);
+                    }
+                }
+            const plan = await cloud.credentialSetups.create({ projectId: r.project_id, deviceId: this.#deviceId, deviceRequestId: r.id, selectedItems: ids, items: sources.map(({ id, name, source, suggested_scope, project_id }) => ({ id, name, source, suggested_scope, ...(project_id ? { project_id } : {}) })) });
+            await this.result(r, { state: 'running', credential_setup: { plan_id: plan.id } });
+            let final = await transferCredentialSetup({ ...ctx, json: false }, cloud, plan, options);
+            while (final.state === 'approved' && !ctx.signal.aborted)
+                final = await cloud.credentialSetups.get(plan.id, { waitSeconds: 30, signal: ctx.signal });
+            const failed = final.state !== 'completed' || final.items.some(i => i.state === 'failed');
+            await this.result(r, { state: failed ? 'failed' : 'done', ...(final.state === 'completed' ? { credential_setup: { plan_id: plan.id } } : {}), ...(failed ? { exit_code: 1 } : {}) });
+        }
+        catch {
+            // No raw source/HTTP/CLI error is allowed into a device result or its conversation.
+            await this.result(r, { state: 'failed', exit_code: 1 });
+        }
+    }
     async execute(r) {
         const ctx = this.#ctx;
         safeId(r.id);
         if (r.state !== 'pending' || r.device_id !== this.#deviceId)
             return;
+        if (r.kind === 'credentials_setup')
+            return this.#credentials(r);
         if (folderRequest(r))
             return this.#folder(r);
         const records = localConversations(ctx);

package/dist/device-folders.d.ts

@@ -46,6 +46,11 @@ type Starter = (ctx: Ctx, folder: string, harness: 'claude' | 'codex', brief: st
  * prompt. The brief goes in on standard input, never in a command line another user can read.
  */
 export declare const startFromFolder: Starter;
+/** How long a start from a folder may take, and how long a child asked to stop may take before it is killed. */
+export declare const startFolderLimits: {
+    timeoutMs: number;
+    killAfterMs: number;
+};
 /**
  * The conversation `shard agents new --json` started, from its whole output: one pretty-printed JSON document
  * (format.ts json), never its last line (staging 2026-10-16: the last line is `}`).

package/dist/device-folders.js

@@ -149,31 +149,55 @@ export const startFromFolder = (ctx, folder, harness, brief, fromConversationId)
             env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, CI: '1', ...(fromConversationId ? { SF_CONVERSATION_ID: fromConversationId } : {}) },
         });
         const out = [], err = [];
-        let outBytes = 0;
-        const stop = () => child.kill('SIGTERM');
-        const timer = setTimeout(stop, 300_000);
-        ctx.signal.addEventListener('abort', stop, { once: true });
+        let outBytes = 0, settled = false, kill;
+        const finish = (error, started) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            ctx.signal.removeEventListener('abort', abort);
+            if (error)
+                reject(error);
+            else
+                resolveStart(started);
+        };
+        // A child that does not end when asked (its own start waiting on a project setup that never finishes) is killed,
+        // and the start fails now with what held it: a device request never stays `running` behind it (production
+        // 2026-10-18: a project_link sat running for over an hour, so its orchestrator input never settled).
+        const stop = () => {
+            child.kill('SIGTERM');
+            kill ??= setTimeout(() => child.kill('SIGKILL'), startFolderLimits.killAfterMs);
+            kill.unref?.();
+        };
+        const abort = () => { stop(); finish(new Error('The conversation start was cancelled.')); };
+        const timer = setTimeout(() => {
+            stop();
+            const minutes = Math.max(1, Math.round(startFolderLimits.timeoutMs / 60_000)), held = lastLine(Buffer.concat(err).toString('utf8'));
+            finish(new Error(`The conversation did not start within ${minutes} minute${minutes === 1 ? '' : 's'}${held ? `: ${held}` : '.'}`));
+        }, startFolderLimits.timeoutMs);
+        ctx.signal.addEventListener('abort', abort, { once: true });
         child.stdout.on('data', (b) => { if ((outBytes += b.length) <= 8 << 20)
             out.push(b); });
         child.stderr.on('data', (b) => { if (err.length < 64)
             err.push(b); });
-        child.once('error', error => { clearTimeout(timer); reject(error); });
+        child.once('error', error => { clearTimeout(kill); finish(error); });
         child.once('close', code => {
-            clearTimeout(timer);
-            ctx.signal.removeEventListener('abort', stop);
+            clearTimeout(kill);
             const text = Buffer.concat(out).toString('utf8');
             try {
                 if (code !== 0)
                     throw new Error(lastLine(Buffer.concat(err).toString('utf8')) || `The conversation did not start (exit ${code}).`);
-                resolveStart(startedConversation(text));
+                finish(null, startedConversation(text));
             }
             catch (error) {
-                reject(error instanceof Error ? error : new Error(String(error)));
+                finish(error instanceof Error ? error : new Error(String(error)));
             }
         });
         child.stdin.end(brief);
     });
 };
+/** How long a start from a folder may take, and how long a child asked to stop may take before it is killed. */
+export const startFolderLimits = { timeoutMs: 300_000, killAfterMs: 10_000 };
 /**
  * The conversation `shard agents new --json` started, from its whole output: one pretty-printed JSON document
  * (format.ts json), never its last line (staging 2026-10-16: the last line is `}`).