@shardflux/cli 0.28.1 → 0.28.3

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[]>;

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