@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/accounts/choices.d.ts

@@ -0,0 +1,41 @@
+import { type Effort } from "../core/effort.js";
+export interface ModeChoice {
+    /** `provider/id` of the model. */
+    model?: string;
+    effort?: Effort;
+    updatedAt: string;
+}
+export interface ChoicePatch {
+    model?: string;
+    effort?: Effort;
+}
+/** Every saved mode of the account. A missing or unreadable file, and any invalid entry, reads as nothing. */
+export declare function readChoices(dir: string, accountId: string): Record<string, ModeChoice>;
+/** Records one or both fields for a mode, keeping the field the patch does not name. */
+export declare function saveChoice(dir: string, accountId: string, mode: string, patch: ChoicePatch): Record<string, ModeChoice>;
+/**
+ * The model and effort a mode starts from: its own saved field, else the fallback mode's. The
+ * fallback itself has no further fallback.
+ */
+export declare function resolveChoice(modes: Record<string, ModeChoice>, mode: string, fallback?: string): {
+    model?: string;
+    effort?: Effort;
+};
+/** A saved selection with the mode it was made in. */
+export interface SavedChoice {
+    mode: string;
+    model?: string;
+    effort?: Effort;
+}
+/** The account's newest saved selection, whichever mode it was made in. */
+export declare function latestChoice(modes: Record<string, ModeChoice>): SavedChoice | undefined;
+/**
+ * The selection a conversation starts from when this account cannot use the model in its own
+ * history: the mode's own fields, then normal's, then the newest selection in any mode.
+ */
+export declare function startChoice(modes: Record<string, ModeChoice>, mode: string): {
+    model?: string;
+    effort?: Effort;
+};
+/** Every model `startChoice` may try, most specific first and without repeats. */
+export declare function startModels(modes: Record<string, ModeChoice>, mode: string): string[];

package/dist/sdk/accounts/choices.js

@@ -0,0 +1,89 @@
+// The model and effort each mode last used on an account. One file per account, in the account's
+// own folder, so removing the account removes its choices. It never holds credentials.
+import { join } from 'node:path';
+import { EFFORTS } from "../core/effort.js";
+import { invalid } from "../core/errors.js";
+import { now, readJsonOr, safeId, writeJson } from "../core/fs.js";
+const MODE = /^[a-z][a-z0-9_-]{0,31}$/;
+const MODEL = /^[^\s/]+\/\S+$/;
+const MAX_MODEL = 200;
+const choicesPath = (dir, accountId) => join(dir, safeId(accountId), 'choices.json');
+const validModel = (model) => model.length <= MAX_MODEL && MODEL.test(model);
+const validEffort = (effort) => typeof effort === 'string' && EFFORTS.includes(effort);
+function validChoice(entry) {
+    const model = typeof entry.model === 'string' && validModel(entry.model) ? entry.model : undefined;
+    const effort = validEffort(entry.effort) ? entry.effort : undefined;
+    if (!model && !effort)
+        return null;
+    return { ...(model ? { model } : {}), ...(effort ? { effort } : {}), updatedAt: typeof entry.updatedAt === 'string' ? entry.updatedAt : now() };
+}
+/** Every saved mode of the account. A missing or unreadable file, and any invalid entry, reads as nothing. */
+export function readChoices(dir, accountId) {
+    const stored = readJsonOr(choicesPath(dir, accountId), null);
+    const modes = {};
+    for (const [mode, entry] of Object.entries(stored?.modes ?? {})) {
+        if (!MODE.test(mode) || !entry || typeof entry !== 'object')
+            continue;
+        const choice = validChoice(entry);
+        if (choice)
+            modes[mode] = choice;
+    }
+    return modes;
+}
+/** Records one or both fields for a mode, keeping the field the patch does not name. */
+export function saveChoice(dir, accountId, mode, patch) {
+    if (!MODE.test(mode))
+        throw invalid('A mode is lowercase letters, digits, - or _, starting with a letter.');
+    if (patch.model !== undefined && (typeof patch.model !== 'string' || !validModel(patch.model)))
+        throw invalid('A model is provider/id.');
+    if (patch.effort !== undefined && !validEffort(patch.effort))
+        throw invalid(`An effort is one of ${EFFORTS.join(', ')}.`);
+    const modes = readChoices(dir, accountId);
+    const current = modes[mode] ?? {};
+    const next = validChoice({
+        ...(patch.model !== undefined ? { model: patch.model } : { model: current.model }),
+        ...(patch.effort !== undefined ? { effort: patch.effort } : { effort: current.effort }),
+        updatedAt: now()
+    });
+    if (!next)
+        throw invalid('Choose a model or an effort.');
+    modes[mode] = next;
+    writeJson(choicesPath(dir, accountId), { modes });
+    return modes;
+}
+/**
+ * The model and effort a mode starts from: its own saved field, else the fallback mode's. The
+ * fallback itself has no further fallback.
+ */
+export function resolveChoice(modes, mode, fallback = 'normal') {
+    const own = modes[mode] ?? {};
+    const base = mode === fallback ? {} : modes[fallback] ?? {};
+    return { model: own.model ?? base.model, effort: own.effort ?? base.effort };
+}
+/** The account's newest saved selection, whichever mode it was made in. */
+export function latestChoice(modes) {
+    let newest;
+    for (const [mode, entry] of Object.entries(modes)) {
+        if (newest && entry.updatedAt <= newest.updatedAt)
+            continue;
+        newest = {
+            choice: { mode, ...(entry.model ? { model: entry.model } : {}), ...(entry.effort ? { effort: entry.effort } : {}) },
+            updatedAt: entry.updatedAt
+        };
+    }
+    return newest?.choice;
+}
+/**
+ * The selection a conversation starts from when this account cannot use the model in its own
+ * history: the mode's own fields, then normal's, then the newest selection in any mode.
+ */
+export function startChoice(modes, mode) {
+    const resolved = resolveChoice(modes, mode);
+    const latest = latestChoice(modes);
+    return { model: resolved.model ?? latest?.model, effort: resolved.effort ?? latest?.effort };
+}
+/** Every model `startChoice` may try, most specific first and without repeats. */
+export function startModels(modes, mode) {
+    const ordered = [modes[mode]?.model, mode === 'normal' ? undefined : modes.normal?.model, latestChoice(modes)?.model];
+    return [...new Set(ordered.filter((reference) => typeof reference === 'string' && reference.length > 0))];
+}

package/dist/sdk/accounts/env.d.ts

@@ -0,0 +1,78 @@
+import type { Account } from "./store.js";
+/** Inherited variables that carry credentials; they would bypass the account's own sign-in. */
+export declare function isCredentialVar(name: string): boolean;
+/** Names of inherited variables to remove from a session's process. */
+export declare function inheritedCredentialVars(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Makes this process safe to run Pi sessions in: credentials come only from an account's own
+ * store, so inherited credential variables are dropped, and Pi's fallback agent folder is an
+ * empty one under the state directory rather than `~/.pi`.
+ */
+export declare function isolateProcess(accountsDir: string, env?: NodeJS.ProcessEnv): void;
+export declare const homeDir: (accountsDir: string, accountId: string) => string;
+/** Pi's agent folder for this account. */
+export declare const configDir: (accountsDir: string, account: Pick<Account, "id">) => string;
+/** The agent-folder entries every account shares. */
+export declare const sharedDir: (accountsDir: string) => string;
+export interface NativeConfig {
+    provider: string;
+    path: string;
+    entries: {
+        name: string;
+        directory: boolean;
+        present: boolean;
+    }[];
+}
+/** What the accounts share, and which of it exists yet. Reads only; nothing is created. */
+export declare function nativeConfig(accountsDir: string): NativeConfig;
+/** The shared folder, created private if no account has linked it yet. */
+export declare function ensureSharedDir(accountsDir: string): string;
+/**
+ * How one shared entry is linked into an account folder. Windows refuses a symbolic link to a
+ * user without the symlink privilege, so each kind has a fallback that needs none.
+ */
+export interface EntryLinker {
+    /** A symbolic link to a file, or a junction to a folder (junctions need no privilege on Windows). */
+    symlink(target: string, path: string, isDir: boolean): void;
+    /** A hard link to a file on the same volume. */
+    hardLink(target: string, path: string): void;
+}
+/** What happened to one shared entry: linked to the shared copy, or left as the account's own. */
+export interface SharedEntry {
+    name: string;
+    state: 'linked' | 'unshared';
+    /** Why the link was refused, when it was. */
+    reason?: string;
+}
+/**
+ * Creates the account's runtime folder and links the shared entries into it. Never throws for a
+ * refused link: each entry is reported, and the account falls back to its own copy.
+ */
+export declare function linkSharedEntries(accountsDir: string, account: Pick<Account, 'id'>, linker?: EntryLinker): {
+    dir: string;
+    entries: SharedEntry[];
+};
+/** Creates the account's runtime folder and links the shared entries into it. */
+export declare function ensureHome(accountsDir: string, account: Pick<Account, 'id'>): string;
+/**
+ * Refuses an agent folder that is (or is inside) a default tool folder, or that is not inside
+ * the harness's own accounts folder.
+ */
+export declare function assertIsolated(accountsDir: string, dir: string): void;
+/** Variables to set, or remove (`null`), when launching a session for this account. */
+export declare function launchEnv(accountsDir: string, account: Pick<Account, 'id'>, inherited?: NodeJS.ProcessEnv): Record<string, string | null>;
+/** What a session needs to run for an account. */
+export interface AccountContext {
+    id: string;
+    provider: 'pi';
+    label: string;
+    /** Variables to set; `null` removes an inherited one. */
+    env: Record<string, string | null>;
+    /** The account's own agent folder. */
+    configDir: string;
+    /** Which shared entries are linked, and which the account keeps as its own. */
+    sharing: SharedEntry[];
+}
+export declare function accountContext(accountsDir: string, account: Account): AccountContext;
+/** The process environment for a `pi` process launched on behalf of this account. */
+export declare function processEnv(account: AccountContext, inherited?: NodeJS.ProcessEnv): Record<string, string>;

package/dist/sdk/accounts/env.js

@@ -0,0 +1,294 @@
+// Isolated launch environments. Every Pi session the harness starts gets its account's own
+// agent folder (`PI_CODING_AGENT_DIR`) under the state directory, and inherited credential
+// variables are removed. A launch that would fall back to `~/.pi` is refused.
+//
+// Settings, skills, prompts, and instructions are shared by every account: the account's agent
+// folder links those entries to `_shared/pi/`. Where the system refuses a link (Windows without
+// the symlink privilege), the entry stays the account's own, and a shared file is copied in so
+// its settings still load. Credentials, sessions, and history stay in the account's own folder.
+import { chmodSync, copyFileSync, linkSync, lstatSync, mkdirSync, readlinkSync, renameSync, rmdirSync, statSync, symlinkSync, unlinkSync, utimesSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { HarnessError } from "../core/errors.js";
+// Config-directory variables the harness always sets itself, including those of other tools so
+// a session can never inherit them.
+const DIR_VARS = ['CODEX_HOME', 'CLAUDE_CONFIG_DIR', 'PI_CODING_AGENT_DIR'];
+/** Inherited variables that carry credentials; they would bypass the account's own sign-in. */
+export function isCredentialVar(name) {
+    const upper = name.toUpperCase();
+    return DIR_VARS.includes(upper) || ['_API_KEY', '_AUTH_TOKEN', '_OAUTH_TOKEN', '_ACCESS_TOKEN'].some((suffix) => upper.endsWith(suffix));
+}
+/** Names of inherited variables to remove from a session's process. */
+export function inheritedCredentialVars(env = process.env) {
+    const names = Object.keys(env).filter(isCredentialVar);
+    for (const name of DIR_VARS)
+        if (!names.includes(name))
+            names.push(name);
+    return names;
+}
+/**
+ * Makes this process safe to run Pi sessions in: credentials come only from an account's own
+ * store, so inherited credential variables are dropped, and Pi's fallback agent folder is an
+ * empty one under the state directory rather than `~/.pi`.
+ */
+export function isolateProcess(accountsDir, env = process.env) {
+    for (const name of inheritedCredentialVars(env))
+        delete env[name];
+    const fallback = join(accountsDir, '.sidecar', 'pi');
+    mkdirSync(fallback, { recursive: true });
+    env.PI_CODING_AGENT_DIR = fallback;
+}
+export const homeDir = (accountsDir, accountId) => join(accountsDir, accountId, 'home');
+/** Pi's agent folder for this account. */
+export const configDir = (accountsDir, account) => join(homeDir(accountsDir, account.id), 'pi');
+/** The agent-folder entries every account shares. */
+export const sharedDir = (accountsDir) => join(accountsDir, '_shared', 'pi');
+function makePrivate(path) {
+    mkdirSync(path, { recursive: true });
+    chmodSync(path, 0o700);
+}
+// Entries every account shares, and whether each is a folder. Credentials (`auth.json`),
+// sessions, and history are never listed.
+const SHARED_ENTRIES = [
+    ['settings.json', false],
+    ['models.json', false],
+    ['AGENTS.md', false],
+    ['SYSTEM.md', false],
+    ['skills', true],
+    ['prompts', true],
+    ['extensions', true],
+    ['themes', true],
+    // Where Pi keeps installed packages: one install serves every account.
+    ['npm', true],
+    ['git', true]
+];
+const present = (path) => {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** What the accounts share, and which of it exists yet. Reads only; nothing is created. */
+export function nativeConfig(accountsDir) {
+    const shared = sharedDir(accountsDir);
+    return { provider: 'pi', path: shared, entries: SHARED_ENTRIES.map(([name, directory]) => ({ name, directory, present: present(join(shared, name)) })) };
+}
+/** The shared folder, created private if no account has linked it yet. */
+export function ensureSharedDir(accountsDir) {
+    const shared = sharedDir(accountsDir);
+    makePrivate(shared);
+    return shared;
+}
+const modified = (path) => {
+    try {
+        return lstatSync(path).mtimeMs;
+    }
+    catch {
+        return -1;
+    }
+};
+/** Moves a real file or folder aside so the shared link can take its place; returns where it went. */
+function backUp(path) {
+    const backup = join(dirname(path), `${basename(path)}.xagent-backup-${Math.floor(Date.now() / 1000)}`);
+    renameSync(path, backup);
+    return backup;
+}
+const nodeLinker = {
+    symlink: (target, path, isDir) => symlinkSync(resolve(target), path, isDir ? 'junction' : 'file'),
+    hardLink: (target, path) => linkSync(target, path)
+};
+const codeOf = (error) => error.code ?? String(error);
+const PRIVILEGE_CODES = ['EPERM', 'EACCES'];
+function createLink(target, path, isDir, linker) {
+    try {
+        linker.symlink(target, path, isDir);
+    }
+    catch (error) {
+        // A file can still be hard-linked without the privilege; a folder has no such fallback.
+        if (isDir || !PRIVILEGE_CODES.includes(codeOf(error)))
+            throw error;
+        linker.hardLink(target, path);
+    }
+}
+const isLink = (path) => {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+};
+// Windows reports some link targets with the `\\?\` prefix.
+const LONG_PREFIX = /^\\\\\?\\/;
+function samePath(a, b) {
+    const normal = (path) => {
+        const full = resolve(path.replace(LONG_PREFIX, ''));
+        return process.platform === 'win32' ? full.toLowerCase() : full;
+    };
+    return normal(a) === normal(b);
+}
+/** A hard link is the same file on disk as its target, so it has the same device and inode. */
+function sameFile(a, b) {
+    try {
+        const left = lstatSync(a);
+        const right = lstatSync(b);
+        return left.ino !== 0 && left.dev === right.dev && left.ino === right.ino;
+    }
+    catch {
+        return false;
+    }
+}
+function isLinkTo(path, target, isDir) {
+    try {
+        const meta = lstatSync(path);
+        if (meta.isSymbolicLink())
+            return samePath(readlinkSync(path), target);
+        return !isDir && meta.isFile() && sameFile(path, target);
+    }
+    catch {
+        return false;
+    }
+}
+/** Removes a link without touching what it points to. A Windows junction needs `rmdir`. */
+function removeLink(path, isDir) {
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (!isDir)
+            throw error;
+        rmdirSync(path);
+    }
+}
+/**
+ * A file the account does not have, for an entry whose link was refused: a copy of the shared one
+ * (with its time kept, so the newest-wins rule does not move it), so the account's settings load.
+ */
+function keepCopy(target, path, isDir) {
+    if (isDir || present(path) || !present(target))
+        return;
+    try {
+        copyFileSync(target, path);
+        const { atime, mtime } = statSync(target);
+        utimesSync(path, atime, mtime);
+    }
+    catch {
+        // The account simply keeps no copy; its sign-in and its own files are not affected.
+    }
+}
+/**
+ * Links one entry to its shared copy. A real entry found in the account folder (from before
+ * sharing, or a tool that replaced the link while saving) becomes the shared copy when there is
+ * none or it is newer; otherwise it is kept as a backup. If the link is then refused, every move
+ * is undone, so the account keeps what it had.
+ */
+function linkOne(name, target, path, isDir, linker) {
+    if (isLinkTo(path, target, isDir)) {
+        if (isDir)
+            mkdirSync(target, { recursive: true });
+        return { name, state: 'linked' };
+    }
+    const undo = [];
+    try {
+        if (isLink(path)) {
+            const previous = readlinkSync(path);
+            removeLink(path, isDir);
+            undo.push(() => nodeLinker.symlink(previous, path, isDir));
+        }
+        else if (present(path)) {
+            if (!present(target)) {
+                renameSync(path, target);
+                undo.push(() => renameSync(target, path));
+            }
+            else if (!isDir && modified(path) > modified(target)) {
+                const backup = backUp(target);
+                undo.push(() => renameSync(backup, target));
+                renameSync(path, target);
+                undo.push(() => renameSync(target, path));
+            }
+            else {
+                const backup = backUp(path);
+                undo.push(() => renameSync(backup, path));
+            }
+        }
+        if (isDir)
+            mkdirSync(target, { recursive: true });
+        createLink(target, path, isDir, linker);
+        return { name, state: 'linked' };
+    }
+    catch (error) {
+        for (const step of undo.reverse()) {
+            try {
+                step();
+            }
+            catch {
+                // The entry stays where that step left it; nothing further can be restored safely.
+            }
+        }
+        keepCopy(target, path, isDir);
+        return { name, state: 'unshared', reason: codeOf(error) };
+    }
+}
+/**
+ * Creates the account's runtime folder and links the shared entries into it. Never throws for a
+ * refused link: each entry is reported, and the account falls back to its own copy.
+ */
+export function linkSharedEntries(accountsDir, account, linker = nodeLinker) {
+    makePrivate(join(accountsDir, account.id));
+    makePrivate(homeDir(accountsDir, account.id));
+    const dir = configDir(accountsDir, account);
+    makePrivate(dir);
+    const shared = ensureSharedDir(accountsDir);
+    const entries = SHARED_ENTRIES.map(([name, isDir]) => linkOne(name, join(shared, name), join(dir, name), isDir, linker));
+    return { dir, entries };
+}
+/** Creates the account's runtime folder and links the shared entries into it. */
+export function ensureHome(accountsDir, account) {
+    return linkSharedEntries(accountsDir, account).dir;
+}
+const inside = (path, parent) => path === parent || path.startsWith(parent.endsWith(sep) ? parent : `${parent}${sep}`);
+/**
+ * Refuses an agent folder that is (or is inside) a default tool folder, or that is not inside
+ * the harness's own accounts folder.
+ */
+export function assertIsolated(accountsDir, dir) {
+    const defaults = ['.codex', '.claude', '.pi'].map((name) => join(homedir() || '/', name));
+    if (defaults.some((folder) => inside(dir, folder)) || !inside(dir, accountsDir)) {
+        throw new HarnessError('account_required', 'A session cannot start outside its isolated account folder.');
+    }
+}
+function sessionEnv(dir, inherited) {
+    const env = {};
+    for (const name of inheritedCredentialVars(inherited))
+        env[name] = null;
+    env.PI_CODING_AGENT_DIR = dir;
+    return env;
+}
+/** Variables to set, or remove (`null`), when launching a session for this account. */
+export function launchEnv(accountsDir, account, inherited = process.env) {
+    const dir = ensureHome(accountsDir, account);
+    assertIsolated(accountsDir, dir);
+    return sessionEnv(dir, inherited);
+}
+export function accountContext(accountsDir, account) {
+    const { dir, entries } = linkSharedEntries(accountsDir, account);
+    assertIsolated(accountsDir, dir);
+    return { id: account.id, provider: 'pi', label: account.label, env: sessionEnv(dir, process.env), configDir: dir, sharing: entries };
+}
+/** The process environment for a `pi` process launched on behalf of this account. */
+export function processEnv(account, inherited = process.env) {
+    const env = {};
+    for (const [name, value] of Object.entries(inherited))
+        if (value !== undefined)
+            env[name] = value;
+    for (const [name, value] of Object.entries(account.env)) {
+        if (value === null)
+            delete env[name];
+        else
+            env[name] = value;
+    }
+    return env;
+}

package/dist/sdk/accounts/secrets.d.ts

@@ -0,0 +1,28 @@
+export interface SecretStore {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface CredentialLockOptions {
+    /** Acquisition only; an acquired callback is never unlocked while still running. */
+    timeoutMs?: number;
+    pollMs?: number;
+}
+/**
+ * Cross-process Lamport bakery lock. Unique participant directories make dead-pid reclamation
+ * safe: a stale cleanup can never unlink a successor's lock. No age-based stealing of live refreshes.
+ * The directory contains only hashed keys, pids, random IDs and tickets, never credential contents.
+ * All processes sharing a backend must use the same coordination directory on a local filesystem.
+ */
+export declare function withCredentialLock<T>(dir: string, key: string, work: () => Promise<T>, options?: CredentialLockOptions): Promise<T>;
+/** `<account id>/<secret name>`: the key an account's secret is stored under. */
+export declare const secretKey: (accountId: string, name: string) => string;
+/** Secrets held only for the life of the process. For tests and throwaway runs. */
+export declare function memorySecretStore(initial?: Record<string, string>): SecretStore & {
+    values: Map<string, string>;
+};
+/**
+ * Secrets in one owner-only JSON file. For a host with no Keychain to offer; anything that can
+ * read the file can read every secret in it.
+ */
+export declare function fileSecretStore(path: string): SecretStore;

package/dist/sdk/accounts/secrets.js

@@ -0,0 +1,147 @@
+// Where credentials live. The harness never writes a secret to its own files: it asks the
+// store the embedding application provides (a Keychain, an encrypted vault), by key.
+import { chmodSync, closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { readJsonOr } from "../core/fs.js";
+/** Exclusive temporary files are private before the first byte is written, not just after rename. */
+function privateWrite(path, value) {
+    const temporary = join(dirname(path), `.credential-${randomUUID()}.tmp`);
+    try {
+        const fd = openSync(temporary, 'wx', 0o600);
+        try {
+            writeFileSync(fd, value);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temporary, path);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/**
+ * Cross-process Lamport bakery lock. Unique participant directories make dead-pid reclamation
+ * safe: a stale cleanup can never unlink a successor's lock. No age-based stealing of live refreshes.
+ * The directory contains only hashed keys, pids, random IDs and tickets, never credential contents.
+ * All processes sharing a backend must use the same coordination directory on a local filesystem.
+ */
+export async function withCredentialLock(dir, key, work, options = {}) {
+    const timeout = options.timeoutMs ?? 30_000;
+    const poll = options.pollMs ?? 20;
+    if (!Number.isFinite(timeout) || timeout < 0 || timeout > 300_000 || !Number.isFinite(poll) || poll < 1 || poll > 1000) {
+        throw new Error('Invalid credential lock wait bounds.');
+    }
+    const started = performance.now();
+    const folder = join(dir, createHash('sha256').update(key).digest('hex'));
+    mkdirSync(folder, { recursive: true, mode: 0o700 });
+    if (!lstatSync(dir).isDirectory() || !lstatSync(folder).isDirectory())
+        throw new Error('Invalid credential lock directory.');
+    chmodSync(dir, 0o700);
+    chmodSync(folder, 0o700);
+    const id = `${process.pid}-${randomUUID()}`;
+    const own = join(folder, id);
+    mkdirSync(own, { mode: 0o700 });
+    const participants = () => {
+        const entries = [];
+        for (const name of readdirSync(folder)) {
+            if (!/^\d+-[0-9a-f-]{36}$/.test(name))
+                throw new Error('Invalid credential lock metadata.');
+            const pid = Number(name.slice(0, name.indexOf('-')));
+            if (!Number.isSafeInteger(pid) || pid <= 0)
+                throw new Error('Invalid credential lock metadata.');
+            let alive = true;
+            try {
+                process.kill(pid, 0);
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    alive = false;
+            }
+            const participant = join(folder, name);
+            if (!alive) {
+                rmSync(participant, { recursive: true, force: true });
+                continue;
+            }
+            try {
+                // The absent ticket is the bakery algorithm's choosing flag.
+                const text = readFileSync(join(participant, 'ticket'), 'utf8');
+                const ticket = Number(text);
+                if (!Number.isSafeInteger(ticket) || ticket <= 0)
+                    throw new Error('Invalid credential lock metadata.');
+                entries.push({ id: name, ticket });
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                if (lstatExists(participant))
+                    entries.push({ id: name, ticket: null });
+            }
+        }
+        return entries;
+    };
+    try {
+        const ticket = Math.max(0, ...participants().map(entry => entry.ticket ?? 0)) + 1;
+        privateWrite(join(own, 'ticket'), String(ticket));
+        for (;;) {
+            const blocked = participants().some(entry => entry.id !== id && (entry.ticket === null || entry.ticket < ticket || (entry.ticket === ticket && entry.id < id)));
+            if (!blocked)
+                return await work();
+            if (performance.now() - started >= timeout)
+                throw new Error('Timed out waiting for credential modification; no credentials were changed.');
+            await new Promise(resolve => setTimeout(resolve, Math.min(poll, Math.max(1, timeout - (performance.now() - started)))));
+        }
+    }
+    finally {
+        rmSync(own, { recursive: true, force: true });
+    }
+}
+function lstatExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/** `<account id>/<secret name>`: the key an account's secret is stored under. */
+export const secretKey = (accountId, name) => `${accountId}/${name}`;
+/** Secrets held only for the life of the process. For tests and throwaway runs. */
+export function memorySecretStore(initial = {}) {
+    const values = new Map(Object.entries(initial));
+    return {
+        values,
+        get: async (key) => values.get(key) ?? null,
+        set: async (key, value) => void values.set(key, value),
+        delete: async (key) => void values.delete(key)
+    };
+}
+/**
+ * Secrets in one owner-only JSON file. For a host with no Keychain to offer; anything that can
+ * read the file can read every secret in it.
+ */
+export function fileSecretStore(path) {
+    const read = () => readJsonOr(path, {});
+    const write = (values) => {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        privateWrite(path, `${JSON.stringify(values, null, 2)}\n`);
+        chmodSync(path, 0o600);
+    };
+    return {
+        get: async (key) => read()[key] ?? null,
+        set: (key, value) => withCredentialLock(`${path}.locks`, 'file', async () => write({ ...read(), [key]: value })),
+        delete: (key) => withCredentialLock(`${path}.locks`, 'file', async () => {
+            const values = read();
+            if (key in values) {
+                delete values[key];
+                write(values);
+            }
+        })
+    };
+}