pikiloop 0.4.0

package/dist/core/logging.js

@@ -0,0 +1,101 @@
+/**
+ * Structured logging with scoped writers and file retention.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const LOG_LEVEL_WEIGHT = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+const DEFAULT_LOG_LEVEL = 'info';
+const DEFAULT_LOG_MAX_LINES = 5000;
+const DEFAULT_LOG_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_LOG_TRIM_EVERY_WRITES = 200;
+function positiveIntEnv(name, fallback) {
+    const raw = String(process.env[name] || '').trim();
+    if (!raw)
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function resolveRetention(options = {}) {
+    return {
+        maxLines: options.maxLines ?? positiveIntEnv('PIKILOOP_LOG_MAX_LINES', DEFAULT_LOG_MAX_LINES),
+        maxAgeMs: options.maxAgeMs ?? positiveIntEnv('PIKILOOP_LOG_MAX_AGE_MS', DEFAULT_LOG_MAX_AGE_MS),
+        trimEveryWrites: options.trimEveryWrites ?? positiveIntEnv('PIKILOOP_LOG_TRIM_EVERY_WRITES', DEFAULT_LOG_TRIM_EVERY_WRITES),
+    };
+}
+export function normalizeLogLevel(value, fallback = DEFAULT_LOG_LEVEL) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (normalized === 'debug' || normalized === 'info' || normalized === 'warn' || normalized === 'error') {
+        return normalized;
+    }
+    return fallback;
+}
+export function getConfiguredLogLevel() {
+    return normalizeLogLevel(process.env.PIKILOOP_LOG_LEVEL, DEFAULT_LOG_LEVEL);
+}
+export function shouldLog(level, configuredLevel = getConfiguredLogLevel()) {
+    return LOG_LEVEL_WEIGHT[level] >= LOG_LEVEL_WEIGHT[configuredLevel];
+}
+export function formatScopedLogLine(scope, message, now = new Date()) {
+    const ts = now.toTimeString().slice(0, 8);
+    return `[${scope} ${ts}] ${message}\n`;
+}
+export function writeScopedLog(scope, message, options = {}) {
+    const level = options.level ?? 'info';
+    if (!shouldLog(level))
+        return false;
+    const line = formatScopedLogLine(scope, message, options.now);
+    if (options.stream === 'stderr')
+        process.stderr.write(line);
+    else
+        process.stdout.write(line);
+    return true;
+}
+function trimRetainedLogContent(content, maxLines) {
+    if (!content)
+        return content;
+    const normalized = content.replace(/\r\n/g, '\n');
+    const hasTrailingNewline = normalized.endsWith('\n');
+    const lines = normalized.split('\n');
+    if (hasTrailingNewline)
+        lines.pop();
+    if (lines.length <= maxLines)
+        return content;
+    return `${lines.slice(-maxLines).join('\n')}\n`;
+}
+export function pruneRetainedLogFile(filePath, options = {}) {
+    const { maxLines, maxAgeMs } = resolveRetention(options);
+    try {
+        const stat = fs.statSync(filePath);
+        if (Date.now() - stat.mtimeMs > maxAgeMs) {
+            fs.writeFileSync(filePath, '');
+            return;
+        }
+        const content = fs.readFileSync(filePath, 'utf8');
+        const trimmed = trimRetainedLogContent(content, maxLines);
+        if (trimmed !== content)
+            fs.writeFileSync(filePath, trimmed);
+    }
+    catch { }
+}
+export function createRetainedLogSink(filePath, options = {}) {
+    const { trimEveryWrites } = resolveRetention(options);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    pruneRetainedLogFile(filePath, options);
+    let writes = 0;
+    return (chunk) => {
+        if (!chunk)
+            return;
+        try {
+            fs.appendFileSync(filePath, chunk);
+            writes++;
+            if (writes === 1 || writes % trimEveryWrites === 0)
+                pruneRetainedLogFile(filePath, options);
+        }
+        catch { }
+    };
+}

package/dist/core/platform.js

@@ -0,0 +1,59 @@
+/**
+ * Cross-platform primitives. All OS-dependent behavior must route through here
+ * so the rest of the codebase stays platform-neutral.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import which from 'which';
+export const IS_WIN = process.platform === 'win32';
+export const IS_MAC = process.platform === 'darwin';
+export const IS_LINUX = process.platform === 'linux';
+/**
+ * User home directory. Re-reads each call so runtime `$HOME`/`$USERPROFILE`
+ * overrides (and tests that mutate them) stay honored. Works on Windows
+ * where `$HOME` is not set by default — `os.homedir()` falls back to
+ * `$USERPROFILE`.
+ */
+export function getHome() {
+    return os.homedir();
+}
+/** Expand a leading `~` (or `~/`, `~\`) to the user's home directory. */
+export function expandTilde(p) {
+    if (!p || p[0] !== '~')
+        return p;
+    const home = getHome();
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/') || (IS_WIN && p.startsWith('~\\'))) {
+        return path.join(home, p.slice(2));
+    }
+    return p;
+}
+/** Locate an executable on PATH, honoring PATHEXT on Windows. */
+export function whichSync(cmd) {
+    return which.sync(cmd, { nothrow: true }) || null;
+}
+/**
+ * Encode an absolute workdir path as a single directory-name segment.
+ * Mirrors Claude Code's scheme under `~/.claude/projects/`: every non
+ * alphanumeric character collapses to `-`. Critically that includes
+ * underscores and dots (e.g. `/path/to/harness_ppt` → `-path-to-harness-ppt`),
+ * which matches the encoding Claude Code uses on disk. Replacing only path
+ * separators leaves a workdir whose name contains `_` (or `.`) pointing at
+ * a directory that does not exist, so session JSONL lookups silently fall
+ * back to an empty/truncated result.
+ */
+export function encodePathAsDirName(p) {
+    return p.replace(/[^a-zA-Z0-9]/g, '-');
+}
+/**
+ * Match a path segment regardless of separator. Useful for probing whether a
+ * resolved script path runs under a given binary (e.g. `tsx`, `ts-node`)
+ * without hardcoding `/` — which fails on Windows.
+ */
+export function pathContainsSegment(p, segment) {
+    const escaped = segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`[\\\\/]${escaped}([\\\\/]|$)`).test(p);
+}
+/** Null-redirect suffix for shell commands. */
+export const DEV_NULL_REDIRECT = IS_WIN ? '2>nul' : '2>/dev/null';

package/dist/core/process-control.js

@@ -0,0 +1,315 @@
+/**
+ * Process lifecycle: restart coordination, watchdog, and process tree termination.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { pathContainsSegment } from './platform.js';
+import { STATE_DIR_NAME } from './constants.js';
+export const PROCESS_RESTART_EXIT_CODE = 75;
+export const PROCESS_RESTART_STATE_FILE_ENV = 'PIKILOOP_RESTART_STATE_FILE';
+const DAEMON_PID_FILENAME = 'pikiloop.pid';
+/** Path to the daemon PID file used by `pikiloop stop`. */
+export function getDaemonPidFilePath() {
+    return path.join(os.homedir(), STATE_DIR_NAME, DAEMON_PID_FILENAME);
+}
+export function writeDaemonPidFile(pid = process.pid) {
+    const filePath = getDaemonPidFilePath();
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, String(pid), 'utf8');
+    }
+    catch { }
+}
+export function clearDaemonPidFile() {
+    try {
+        fs.unlinkSync(getDaemonPidFilePath());
+    }
+    catch { }
+}
+export function readDaemonPidFile() {
+    try {
+        const raw = fs.readFileSync(getDaemonPidFilePath(), 'utf8').trim();
+        const pid = Number.parseInt(raw, 10);
+        return Number.isFinite(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True if a process with `pid` is currently running (POSIX kill -0 / win32 tasklist). */
+export function isProcessAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err?.code;
+        // EPERM means the process exists but we cannot signal it — still alive.
+        return code === 'EPERM';
+    }
+}
+const runtimes = new Map();
+let nextRuntimeId = 1;
+let restartInFlight = false;
+export function shellSplit(str) {
+    const args = [];
+    let cur = '';
+    let inSingle = false;
+    let inDouble = false;
+    for (const ch of str) {
+        if (ch === '\'' && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (ch === '"' && !inSingle) {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (ch === ' ' && !inSingle && !inDouble) {
+            if (cur)
+                args.push(cur);
+            cur = '';
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur)
+        args.push(cur);
+    return args;
+}
+function isNpxBinary(bin) {
+    return path.basename(bin, path.extname(bin)).toLowerCase() === 'npx';
+}
+export function ensureNonInteractiveRestartArgs(bin, args) {
+    if (!isNpxBinary(bin))
+        return args;
+    if (args.includes('--yes') || args.includes('-y'))
+        return args;
+    return ['--yes', ...args];
+}
+export function getDefaultRestartCmd() {
+    const argv0 = process.argv[0] ?? '';
+    const argv1 = process.argv[1] ?? '';
+    if (argv1.endsWith('.ts') || pathContainsSegment(argv1, 'tsx') || pathContainsSegment(argv1, 'ts-node')) {
+        const isTsxLoader = !pathContainsSegment(argv0, 'tsx')
+            && process.execArgv?.some(arg => arg.includes('tsx'));
+        const parts = isTsxLoader ? ['tsx', argv1] : process.argv.slice(0, 2);
+        return parts.map(arg => arg.includes(' ') ? `"${arg}"` : arg).join(' ');
+    }
+    // Running from an installed package (e.g. npm install -g) — reuse the same entry point
+    if (argv1.endsWith('.js') && (argv1.includes('pikiloop') || argv1.includes('pikiloop'))) {
+        const nodeBin = argv0.includes(' ') ? `"${argv0}"` : argv0;
+        const entry = argv1.includes(' ') ? `"${argv1}"` : argv1;
+        return `${nodeBin} ${entry}`;
+    }
+    return 'npx --yes pikiloop@latest';
+}
+export function buildRestartCommand(argv, restartCmd = process.env.PIKILOOP_RESTART_CMD || getDefaultRestartCmd()) {
+    const [bin, ...rawArgs] = shellSplit(restartCmd);
+    return {
+        bin,
+        args: [...ensureNonInteractiveRestartArgs(bin, rawArgs), ...argv],
+    };
+}
+export function registerProcessRuntime(runtime) {
+    const id = nextRuntimeId++;
+    runtimes.set(id, runtime);
+    return () => {
+        runtimes.delete(id);
+    };
+}
+export function getRegisteredRuntimeCount() {
+    return runtimes.size;
+}
+export function getActiveTaskCount() {
+    let total = 0;
+    for (const runtime of runtimes.values()) {
+        total += Math.max(0, runtime.getActiveTaskCount?.() || 0);
+    }
+    return total;
+}
+export function createRestartStateFilePath(ownerPid = process.pid) {
+    const dir = path.join(os.tmpdir(), 'pikiloop');
+    fs.mkdirSync(dir, { recursive: true });
+    return path.join(dir, `restart-${ownerPid}.json`);
+}
+export function clearRestartStateFile(filePath) {
+    if (!filePath)
+        return;
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch { }
+}
+export function writeRestartStateFile(filePath, env) {
+    const payload = { version: 1, env };
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(payload), 'utf8');
+}
+export function consumeRestartStateFile(filePath) {
+    if (!filePath)
+        return {};
+    try {
+        const raw = fs.readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed?.version !== 1 || !parsed.env || typeof parsed.env !== 'object')
+            return {};
+        return Object.fromEntries(Object.entries(parsed.env)
+            .filter((entry) => typeof entry[0] === 'string' && typeof entry[1] === 'string')
+            .map(([key, value]) => [key, value.trim()]));
+    }
+    catch {
+        return {};
+    }
+    finally {
+        clearRestartStateFile(filePath);
+    }
+}
+function mergeEnvValues(target, patch) {
+    for (const [key, rawValue] of Object.entries(patch)) {
+        const value = rawValue.trim();
+        if (!value)
+            continue;
+        if (!target[key]) {
+            target[key] = value;
+            continue;
+        }
+        const merged = new Set([
+            ...target[key].split(',').map(item => item.trim()).filter(Boolean),
+            ...value.split(',').map(item => item.trim()).filter(Boolean),
+        ]);
+        target[key] = [...merged].join(',');
+    }
+}
+function collectRestartEnv() {
+    const env = {};
+    for (const runtime of runtimes.values()) {
+        const patch = runtime.buildRestartEnv?.() || {};
+        mergeEnvValues(env, patch);
+    }
+    return env;
+}
+async function prepareRuntimesForRestart(log) {
+    for (const runtime of [...runtimes.values()]) {
+        const label = runtime.label ? `${runtime.label}: ` : '';
+        try {
+            await runtime.prepareForRestart?.();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log?.(`restart cleanup failed (${label}${message})`);
+        }
+    }
+}
+function buildRestartEnvForSpawn(extraEnv) {
+    const env = {
+        ...process.env,
+        ...extraEnv,
+        npm_config_yes: process.env.npm_config_yes || 'true',
+    };
+    delete env.PIKILOOP_DAEMON_CHILD;
+    delete env[PROCESS_RESTART_STATE_FILE_ENV];
+    return env;
+}
+function spawnReplacementProcess(bin, args, env, log) {
+    // npx/npx.cmd needs shell resolution; node.exe does not
+    const needsShell = process.platform === 'win32' && !bin.endsWith('node.exe');
+    const child = spawn(needsShell ? `"${bin}"` : bin, args, {
+        stdio: 'inherit',
+        detached: true,
+        shell: needsShell || undefined,
+        env,
+        cwd: process.cwd(),
+    });
+    child.unref();
+    log?.(`restart: new process spawned (PID ${child.pid})`);
+    return child;
+}
+export async function requestProcessRestart(opts = {}) {
+    if (restartInFlight) {
+        return {
+            ok: true,
+            restarting: true,
+            error: null,
+            activeTasks: 0,
+        };
+    }
+    const activeTasks = getActiveTaskCount();
+    if (activeTasks > 0) {
+        return {
+            ok: false,
+            restarting: false,
+            error: `${activeTasks} task(s) still running. Wait for them to finish or try again.`,
+            activeTasks,
+        };
+    }
+    restartInFlight = true;
+    const log = opts.log;
+    const exit = opts.exit || process.exit;
+    try {
+        const extraEnv = collectRestartEnv();
+        await prepareRuntimesForRestart(log);
+        if (process.env.PIKILOOP_DAEMON_CHILD === '1') {
+            const restartStateFile = process.env[PROCESS_RESTART_STATE_FILE_ENV];
+            if (restartStateFile) {
+                if (Object.keys(extraEnv).length)
+                    writeRestartStateFile(restartStateFile, extraEnv);
+                else
+                    clearRestartStateFile(restartStateFile);
+            }
+            log?.('restart: handing off to daemon supervisor');
+            exit(PROCESS_RESTART_EXIT_CODE);
+            return { ok: true, restarting: true, error: null, activeTasks: 0 };
+        }
+        const { bin, args } = buildRestartCommand(opts.argv || process.argv.slice(2), opts.restartCmd);
+        log?.(`restart: spawning \`${bin} ${args.join(' ')}\``);
+        spawnReplacementProcess(bin, args, buildRestartEnvForSpawn(extraEnv), log);
+        exit(0);
+        return { ok: true, restarting: true, error: null, activeTasks: 0 };
+    }
+    catch (err) {
+        restartInFlight = false;
+        return {
+            ok: false,
+            restarting: false,
+            error: err instanceof Error ? err.message : String(err),
+            activeTasks: 0,
+        };
+    }
+}
+export function terminateProcessTree(target, opts = {}) {
+    const pid = typeof target === 'number' ? target : target?.pid;
+    if (!pid || pid <= 0)
+        return;
+    const signal = opts.signal ?? 'SIGTERM';
+    const forceSignal = opts.forceSignal ?? null;
+    const forceAfterMs = opts.forceAfterMs ?? 0;
+    const killPid = (targetPid, nextSignal) => {
+        try {
+            if (process.platform === 'win32') {
+                const args = ['/pid', String(targetPid), '/t'];
+                if (nextSignal === 'SIGKILL')
+                    args.push('/f');
+                const killer = spawn('taskkill', args, { stdio: 'ignore', windowsHide: true });
+                killer.unref();
+                return;
+            }
+            process.kill(-targetPid, nextSignal);
+        }
+        catch {
+            try {
+                process.kill(targetPid, nextSignal);
+            }
+            catch { }
+        }
+    };
+    killPid(pid, signal);
+    if (forceSignal == null || forceAfterMs <= 0 || forceSignal === signal)
+        return;
+    const timer = setTimeout(() => killPid(pid, forceSignal), forceAfterMs);
+    timer.unref?.();
+}

package/dist/core/secrets/index.js

@@ -0,0 +1,42 @@
+/**
+ * Barrel for the pikiloop credential vault.
+ *
+ * Pikiloop owns its own credential layer rather than delegating to per-agent
+ * config files: when an agent is spawned, the active Profile's credentials
+ * are resolved on the fly and injected as env vars / generated config files.
+ * This means setting.json never holds a raw secret in the default flow, and
+ * adding a new agent (Hermes, OpenCode, …) does not duplicate credential UX.
+ */
+export { KEYCHAIN_SERVICE, isCredentialRef, describeCredentialRef } from './ref.js';
+export { resolveCredential, tryResolveCredential } from './resolver.js';
+export { isKeychainAvailable, readKeychain, writeKeychain, deleteKeychain, } from './store.js';
+export { sealInline, unsealInline } from './inline-seal.js';
+import { writeKeychain, deleteKeychain, isKeychainAvailable } from './store.js';
+import { sealInline } from './inline-seal.js';
+/**
+ * Convenience: store a freshly-pasted secret using the safest available
+ * backend. Returns the CredentialRef the caller should persist alongside
+ * the Provider record.
+ */
+export async function persistSecret(account, plaintext) {
+    if (await isKeychainAvailable()) {
+        try {
+            await writeKeychain(account, plaintext);
+            return { source: 'keychain', account };
+        }
+        catch {
+            // fall through to inline seal
+        }
+    }
+    return { source: 'inline', sealed: sealInline(plaintext) };
+}
+/** Best-effort cleanup when a Provider is deleted. */
+export async function forgetSecret(ref) {
+    if (ref.source === 'keychain') {
+        try {
+            await deleteKeychain(ref.account);
+        }
+        catch { }
+    }
+    // env / command / inline references have nothing to clean
+}

package/dist/core/secrets/inline-seal.js

@@ -0,0 +1,60 @@
+/**
+ * Machine-bound AES-256-GCM seal for credential values when no OS keychain
+ * is available. The derived key mixes hostname + a per-install random salt
+ * stored alongside ~/.pikiloop/setting.json, so a sealed blob copied to a
+ * different machine will not decrypt.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { STATE_DIR_NAME } from '../constants.js';
+const SALT_FILE = path.join(os.homedir(), STATE_DIR_NAME, '.machine-salt');
+const VERSION_TAG = 'v1';
+function readOrCreateSalt() {
+    try {
+        const raw = fs.readFileSync(SALT_FILE);
+        if (raw.length >= 32)
+            return raw.subarray(0, 32);
+    }
+    catch { }
+    const salt = crypto.randomBytes(32);
+    try {
+        fs.mkdirSync(path.dirname(SALT_FILE), { recursive: true });
+        fs.writeFileSync(SALT_FILE, salt, { mode: 0o600 });
+    }
+    catch { }
+    return salt;
+}
+function deriveKey() {
+    const salt = readOrCreateSalt();
+    const material = Buffer.concat([
+        Buffer.from(os.hostname() || 'pikiloop'),
+        Buffer.from(os.userInfo().username || ''),
+        salt,
+    ]);
+    return crypto.createHash('sha256').update(material).digest();
+}
+/** Returns base64 string `v1:<iv>:<ciphertext>:<tag>`. */
+export function sealInline(plaintext) {
+    const key = deriveKey();
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return `${VERSION_TAG}:${iv.toString('base64')}:${encrypted.toString('base64')}:${tag.toString('base64')}`;
+}
+export function unsealInline(sealed) {
+    const parts = sealed.split(':');
+    if (parts.length !== 4 || parts[0] !== VERSION_TAG) {
+        throw new Error(`Invalid sealed blob: ${parts[0]}`);
+    }
+    const [, ivB64, ctB64, tagB64] = parts;
+    const key = deriveKey();
+    const iv = Buffer.from(ivB64, 'base64');
+    const ct = Buffer.from(ctB64, 'base64');
+    const tag = Buffer.from(tagB64, 'base64');
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
+}

package/dist/core/secrets/ref.js

@@ -0,0 +1,33 @@
+/**
+ * Credential reference — never store raw secrets in setting.json.
+ *
+ * Each credential is described by a small reference that can be dereferenced
+ * at use time:
+ *   - keychain: stored in OS keychain, looked up by service+account
+ *   - env:      read from process.env at use time
+ *   - command:  exec a command and use its stdout (e.g. `op read`, `gh auth token`)
+ *   - inline:   AES-GCM sealed blob bound to this machine (fallback)
+ */
+/** Stable service name used when writing to the OS keychain. */
+export const KEYCHAIN_SERVICE = 'pikiloop';
+export function isCredentialRef(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const r = value;
+    switch (r.source) {
+        case 'keychain': return typeof value.account === 'string';
+        case 'env': return typeof value.varName === 'string';
+        case 'command': return Array.isArray(value.argv);
+        case 'inline': return typeof value.sealed === 'string';
+        default: return false;
+    }
+}
+/** Short, non-sensitive description of a credential reference for UI display. */
+export function describeCredentialRef(ref) {
+    switch (ref.source) {
+        case 'keychain': return `keychain:${ref.account}`;
+        case 'env': return `env:${ref.varName}`;
+        case 'command': return `cmd:${ref.argv[0] || '?'}…`;
+        case 'inline': return 'inline (sealed)';
+    }
+}

package/dist/core/secrets/resolver.js

@@ -0,0 +1,65 @@
+/**
+ * Resolve a CredentialRef to a plaintext secret.
+ *
+ * Resolved values are returned to the caller and immediately consumed (e.g.
+ * injected into a child process env at spawn time). Pikiloop never persists
+ * the resolved plaintext in long-lived state.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readKeychain } from './store.js';
+import { unsealInline } from './inline-seal.js';
+const execFileP = promisify(execFile);
+export async function resolveCredential(ref, opts = {}) {
+    const env = opts.env ?? process.env;
+    switch (ref.source) {
+        case 'keychain': {
+            const value = await readKeychain(ref.account);
+            if (!value)
+                throw new Error(`Keychain entry not found: ${ref.account}`);
+            return value;
+        }
+        case 'env': {
+            const value = env[ref.varName];
+            if (!value)
+                throw new Error(`Environment variable not set: ${ref.varName}`);
+            return value;
+        }
+        case 'command': {
+            if (!ref.argv.length)
+                throw new Error('Empty command argv');
+            const [cmd, ...args] = ref.argv;
+            try {
+                const { stdout } = await execFileP(cmd, args, {
+                    timeout: opts.commandTimeoutMs ?? 5000,
+                    encoding: 'utf8',
+                    env,
+                });
+                const value = String(stdout).trim();
+                if (!value)
+                    throw new Error(`Command produced empty output: ${cmd}`);
+                return value;
+            }
+            catch (e) {
+                throw new Error(`Credential command failed (${cmd}): ${e?.message || e}`);
+            }
+        }
+        case 'inline': {
+            try {
+                return unsealInline(ref.sealed);
+            }
+            catch (e) {
+                throw new Error(`Inline credential decryption failed: ${e?.message || e}`);
+            }
+        }
+    }
+}
+/** Resolve to null on error rather than throwing — useful for status checks. */
+export async function tryResolveCredential(ref, opts = {}) {
+    try {
+        return await resolveCredential(ref, opts);
+    }
+    catch {
+        return null;
+    }
+}