aptly 0.1.1 → 0.1.3

package/README.en.md

@@ -6,7 +6,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/aptly)](https://www.npmjs.com/package/aptly)
 [![MIT license](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/abruption/aptly/blob/main/LICENSE)
 
-**Model and reasoning recommendations for subagents.**
+**Model and reasoning recommendations for subagents, powered by the OpenAI Decisions API.**
 
 [한국어](README.md) · **English** · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
 
@@ -20,15 +20,17 @@ Our own tests showed **about 52–58% lower API-equivalent costs**. See the [tes
 
 ## Quick start
 
-Requires Node.js **24 or later** and Claude Code or Codex. Use the commands below **after 0.1.1 is published on npm**.
+Requires Node.js **24 or later** and Claude Code or Codex. Install the latest stable version globally with these commands.
 
 ```sh
-npm install -g aptly@0.1.1
+npm install -g aptly@latest --allow-scripts=aptly
 aptly setup --client all --mode defaults
 aptly --version
 ```
 
-The version command should print `0.1.1`.
+Check the installed version with `aptly --version`. On supported npm versions, `--allow-scripts=aptly` allows Aptly’s installation script. If your npm does not support this option, follow the explicit installation and setup steps in the [installation guide](docs/guide/en.md#installation).
+
+Before upgrading, stop all related host, MCP, and CLI processes and review the ledger transition in the [installation and upgrade guide](docs/guide/en.md#installation).
 
 During installation, `postinstall` registers the MCP server and a `PreToolUse` Hook in existing host configuration directories. Run `setup` explicitly if automatic registration was skipped or a host has no configuration directory yet. Other settings and Hooks, and any existing Aptly launch command and environment, are preserved.
 

package/README.ja.md

@@ -6,7 +6,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/aptly)](https://www.npmjs.com/package/aptly)
 [![MIT license](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/abruption/aptly/blob/main/LICENSE)
 
-**Model and reasoning recommendations for subagents.**
+**Model and reasoning recommendations for subagents, powered by the OpenAI Decisions API.**
 
 [한국어](README.md) · [English](README.en.md) · [简体中文](README.zh-CN.md) · **日本語**
 
@@ -20,15 +20,17 @@ Aptly は必要最小限のタスク要約を OpenAI Decisions API で分類し
 
 ## クイックスタート
 
-Node.js **24 以上**と Claude Code または Codex が必要です。以下のコマンドは **0.1.1 が npm で公開された後**に使用してください。
+Node.js **24 以上**と Claude Code または Codex が必要です。以下のコマンドで最新の安定版をグローバルインストールしてください。
 
 ```sh
-npm install -g aptly@0.1.1
+npm install -g aptly@latest --allow-scripts=aptly
 aptly setup --client all --mode defaults
 aptly --version
 ```
 
-バージョン確認コマンドの出力が `0.1.1` であることを確認してください。
+`aptly --version` でインストール済みのバージョンを確認してください。対応する npm では、`--allow-scripts=aptly` で Aptly のインストールスクリプトを許可します。このオプションに対応していない npm では、[インストール案内](docs/guide/ja.md#インストール)の明示的なインストール・設定手順に従ってください。
+
+アップグレード前に、関連するホスト・MCP・CLI の全プロセスを停止し、[インストールとアップグレードの案内](docs/guide/ja.md#インストール)で台帳の移行手順を確認してください。
 
 インストール時の `postinstall` は、既存のホスト設定ディレクトリに MCP と `PreToolUse` Hook を登録します。自動登録をスキップした場合や、ホストに設定ディレクトリがまだない場合も、`setup` を明示的に実行して登録できます。他の既存設定・Hook と、既存の Aptly の実行コマンド・環境は保持します。
 

package/README.md

@@ -6,7 +6,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/aptly)](https://www.npmjs.com/package/aptly)
 [![MIT license](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/abruption/aptly/blob/main/LICENSE)
 
-**Model and reasoning recommendations for subagents.**
+**Model and reasoning recommendations for subagents, powered by the OpenAI Decisions API.**
 
 **한국어** · [English](README.en.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
 
@@ -20,15 +20,17 @@ Aptly는 최소한의 작업 요약을 OpenAI Decisions API로 분류하고 허
 
 ## 빠른 시작
 
-Node.js **24 이상**과 Claude Code 또는 Codex가 필요합니다. 아래 명령은 **0.1.1이 npm에 게시된 후** 사용하십시오.
+Node.js **24 이상**과 Claude Code 또는 Codex가 필요합니다. 다음 명령으로 최신 안정 버전을 전역 설치하십시오.
 
 ```sh
-npm install -g aptly@0.1.1
+npm install -g aptly@latest --allow-scripts=aptly
 aptly setup --client all --mode defaults
 aptly --version
 ```
 
-버전 확인 명령의 출력은 `0.1.1`입니다.
+`aptly --version`으로 설치된 버전을 확인하십시오. `--allow-scripts=aptly`는 지원하는 npm에서 Aptly의 설치 스크립트를 허용합니다. 이 옵션을 지원하지 않는 npm은 [설치 안내](docs/guide/ko.md#설치)의 명시적 설치·설정 절차를 따르십시오.
+
+업그레이드 전에는 관련 호스트·MCP·CLI 프로세스를 모두 중지하고 [설치·업그레이드 안내](docs/guide/ko.md#설치)의 원장 전환 절차를 확인하십시오.
 
 설치 시 `postinstall`은 기존 호스트 설정 디렉터리에 MCP와 `PreToolUse` Hook을 등록합니다. 명시적인 `setup`은 자동 등록을 건너뛰었거나 아직 설정 디렉터리가 없는 호스트에도 사용할 수 있습니다. 기존 다른 설정·Hook과 기존 Aptly 실행 명령·환경은 보존합니다.
 

package/README.zh-CN.md

@@ -6,7 +6,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/aptly)](https://www.npmjs.com/package/aptly)
 [![MIT license](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/abruption/aptly/blob/main/LICENSE)
 
-**Model and reasoning recommendations for subagents.**
+**Model and reasoning recommendations for subagents, powered by the OpenAI Decisions API.**
 
 [한국어](README.md) · [English](README.en.md) · **简体中文** · [日本語](README.ja.md)
 
@@ -20,15 +20,17 @@ Aptly 使用 OpenAI Decisions API 对简要任务摘要进行分类，并推荐
 
 ## 快速开始
 
-需要 Node.js **24 或更高版本**以及 Claude Code 或 Codex。请在 **0.1.1 发布到 npm 后**使用以下命令。
+需要 Node.js **24 或更高版本**以及 Claude Code 或 Codex。请使用以下命令全局安装最新稳定版。
 
 ```sh
-npm install -g aptly@0.1.1
+npm install -g aptly@latest --allow-scripts=aptly
 aptly setup --client all --mode defaults
 aptly --version
 ```
 
-版本检查命令应输出 `0.1.1`。
+请使用 `aptly --version` 确认已安装的版本。在支持此选项的 npm 中，`--allow-scripts=aptly` 允许执行 Aptly 的安装脚本。如果 npm 不支持此选项，请按照[安装指南](docs/guide/zh-CN.md#安装)中的显式安装与配置步骤操作。
+
+升级前，请停止所有相关宿主、MCP 和 CLI 进程，并查看[安装与升级指南](docs/guide/zh-CN.md#安装)中的账本迁移步骤。
 
 安装时的 `postinstall` 会在现有宿主配置目录中注册 MCP 和 `PreToolUse` Hook。如果跳过了自动注册，或宿主尚无配置目录，也可以显式运行 `setup`。其他现有配置与 Hook，以及 Aptly 原有的启动命令和环境均会保留。
 

package/dist/bin/aptly.js

@@ -9,14 +9,29 @@ import { collectDiagnostics } from '../src/diagnostics.js';
 import { exportDiagnosticReport } from '../src/report.js';
 import { fetchModelInfo, saveModelInfo } from '../src/model-info.js';
 import { errorCode } from '../src/types.js';
-import { setupHosts, removeSetup, setDefaults, setEnvironment, configurableEnvironmentKeys } from '../src/setup.js';
+import { setupHosts, removeSetup, setDefaults, setEnvironment, configurableEnvironmentKeys, migrateLauncher } from '../src/setup.js';
 import { readEnvironmentValue } from '../src/cli-input.js';
-import { setApiKey } from '../src/credential-setup.js';
+import { prepareApiKey } from '../src/credential-setup.js';
+import { updateGlobalInstallation } from '../src/update.js';
+import { updateNotification } from '../src/update-notifier.js';
 const [command = 'serve', ...args] = process.argv.slice(2);
 const output = (value) => process.stdout.write(JSON.stringify(value, null, 2) + '\n');
 try {
     if (['--help', '-h', 'help'].includes(command)) {
-        process.stdout.write('Aptly (preview)\n\nCommands:\n  serve                 Start the stdio MCP server (default: fixture/shadow).\n  capabilities          Print the active catalog; no API call.\n  catalog               Print the active catalog; no API call.\n  catalog refresh --output ABS_PATH  Fetch official model descriptions to a private cache.\n  recommend             Recommend for a task JSON on stdin; no host evidence required.\n  inspect CLIENT FILE   Inspect an explicit JSON settings inventory; no API call.\n  config CLIENT         Print an MCP registration fragment; does not edit settings.\n  set default           Add missing default MCP environment settings.\n  set env ENV_KEY       Prompt for an MCP environment value.\n  setup                 Register MCP and automatic PreToolUse Hooks.\n  remove                Remove only unchanged Aptly-owned registration.\n  report                Write redacted local diagnostic attachments (default: md + json).\n    --format md|json|both  Select report formats.\n    --output-dir DIR      Private output directory (default: reports).\n  --version             Print the package version.\n\nUse aptly set env OPENAI_API_KEY for OS storage, or pass it through the MCP environment.\nPaid mode additionally requires\nROUTER_PROVIDER=decisions and an absolute ROUTER_LEDGER_PATH in a private directory.\nROUTER_CONFIG_PATH is an optional private operator configuration file.\n');
+        process.stdout.write('Aptly (preview)\n\nCommands:\n  serve                 Start the stdio MCP server (default: fixture/shadow).\n  capabilities          Print the active catalog; no API call.\n  catalog               Print the active catalog; no API call.\n  catalog refresh --output ABS_PATH  Fetch official model descriptions to a private cache.\n  recommend             Recommend for a task JSON on stdin; no host evidence required.\n  inspect CLIENT FILE   Inspect an explicit JSON settings inventory; no API call.\n  config CLIENT         Print an MCP registration fragment; does not edit settings.\n  set default           Add missing default MCP environment settings.\n  set env ENV_KEY       Prompt for an MCP environment value.\n  setup                 Register MCP and automatic PreToolUse Hooks.\n  remove                Remove only unchanged Aptly-owned registration.\n  update                Update this verified global npm installation.\n  report                Write redacted local diagnostic attachments (default: md + json).\n    --format md|json|both  Select report formats.\n    --output-dir DIR      Private output directory (default: reports).\n  --version             Print the package version.\n\nUse aptly set env OPENAI_API_KEY for OS storage, or pass it through the MCP environment.\nPaid mode additionally requires\nROUTER_PROVIDER=decisions and an absolute ROUTER_LEDGER_PATH in a private directory.\nROUTER_CONFIG_PATH is an optional private operator configuration file.\n');
+    }
+    else if (command === 'update') {
+        if (args.length === 1 && args[0] === '--help')
+            process.stdout.write('Usage: aptly update\nRequires a verified global npm installation. Stop other hosts/MCP/CLI writers first.\nUpdates the same npm prefix without lifecycle setup. Run aptly setup and restart hosts afterward; existing launchers are preserved.\n');
+        else {
+            if (args.length)
+                throw new Error('update_invalid_options');
+            const packageRoot = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../' : '../../', import.meta.url));
+            const result = updateGlobalInstallation({ packageRoot });
+            output(result);
+            if (result.status === 'error')
+                process.exitCode = 1;
+        }
     }
     else if (command === '--version')
         process.stdout.write(VERSION + '\n');
@@ -39,7 +54,7 @@ try {
     }
     else if (command === 'set') {
         if (args.length === 1 && args[0] === '--help')
-            process.stdout.write('Usage: aptly set default [--client codex|claude|all]\n       aptly set env ENV_KEY [--client codex|claude|all] [--stdin]\nValues are entered interactively with hidden input; --stdin explicitly reads a value from standard input. Existing defaults and launchers are preserved. OPENAI_API_KEY is stored in the OS credential store; host files contain references only. Restart MCP after changes.\n');
+            process.stdout.write('Usage: aptly set default [--client codex|claude|all]\n       aptly set env ENV_KEY [--client codex|claude|all] [--stdin | --check]\n--check diagnoses OPENAI_API_KEY registration without reading or storing a key.\nValues are entered interactively with hidden input; --stdin explicitly reads a value from standard input. Existing defaults and launchers are preserved. OPENAI_API_KEY is stored in the OS credential store; host files contain references only. Restart MCP after changes.\n');
         else {
             const action = args[0];
             let key;
@@ -54,12 +69,17 @@ try {
                 throw new Error('set_invalid_options');
             let clients = ['codex', 'claude'];
             let fromStdin = false;
+            let checkOnly = false;
             const seen = new Set();
             for (let i = start; i < args.length; i++) {
                 const flag = args[i];
                 if (seen.has(flag))
                     throw new Error('set_invalid_options');
                 seen.add(flag);
+                if (flag === '--check' && action === 'env' && key === 'OPENAI_API_KEY') {
+                    checkOnly = true;
+                    continue;
+                }
                 if (flag === '--stdin' && action === 'env') {
                     fromStdin = true;
                     continue;
@@ -72,33 +92,57 @@ try {
                     throw new Error('set_invalid_options');
             }
             const packageRoot = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../' : '../../', import.meta.url));
+            if (checkOnly && fromStdin)
+                throw new Error('set_invalid_options');
+            const credential = key === 'OPENAI_API_KEY' ? prepareApiKey({ clients, packageRoot }) : undefined;
             let value = '';
-            try {
-                if (action === 'env')
-                    value = await readEnvironmentValue({ key: key, fromStdin });
-                const result = action === 'default' ? setDefaults({ clients, packageRoot }) : key === 'OPENAI_API_KEY' ? setApiKey(value, { clients, packageRoot }) : setEnvironment(key, value, { clients, packageRoot });
-                output(result);
-                if (result.status === 'partial')
+            if (credential && (checkOnly || credential.result.status === 'partial')) {
+                output(credential.result);
+                if (credential.result.status === 'partial')
                     process.exitCode = 1;
             }
-            finally {
-                value = '';
-            }
+            else
+                try {
+                    if (action === 'env')
+                        value = await readEnvironmentValue({ key: key, fromStdin });
+                    const result = action === 'default' ? setDefaults({ clients, packageRoot }) : key === 'OPENAI_API_KEY' ? credential.apply(value) : setEnvironment(key, value, { clients, packageRoot });
+                    output(result);
+                    if (result.status === 'partial')
+                        process.exitCode = 1;
+                }
+                finally {
+                    value = '';
+                }
         }
     }
     else if (['setup', 'remove'].includes(command)) {
         if (args.length === 1 && args[0] === '--help')
-            process.stdout.write('Usage: aptly setup [--client codex|claude|all] [--mode defaults|advisory] [--automatic]\n       aptly remove [--client codex|claude|all]\nSetup merges MCP and PreToolUse registration. Codex requires native /hooks trust review.\nAutomatic setup skips CI, APTLY_SKIP_SETUP=1, and absent host directories. No keys are stored.\n');
+            process.stdout.write('Usage: aptly setup [--client codex|claude|all] [--mode defaults|advisory] [--automatic]\n       aptly setup --client codex|claude --migrate-launcher [--include-existing] [--dry-run]\n       aptly remove [--client codex|claude|all]\nSetup merges MCP and PreToolUse registration. Codex requires native /hooks trust review.\nAutomatic setup skips CI, APTLY_SKIP_SETUP=1, and absent host directories. No keys are stored.\n');
         else {
             let clients = ['codex', 'claude'];
             let mode = 'defaults';
             let automatic = false;
+            let migrate = false;
+            let dryRun = false;
+            let includeExisting = false;
             const seen = new Set();
             for (let i = 0; i < args.length; i++) {
                 const flag = args[i];
                 if (seen.has(flag))
                     throw new Error('setup_invalid_options');
                 seen.add(flag);
+                if (flag === '--migrate-launcher' && command === 'setup') {
+                    migrate = true;
+                    continue;
+                }
+                if (flag === '--include-existing' && command === 'setup') {
+                    includeExisting = true;
+                    continue;
+                }
+                if (flag === '--dry-run' && command === 'setup') {
+                    dryRun = true;
+                    continue;
+                }
                 if (flag === '--automatic' && command === 'setup') {
                     automatic = true;
                     continue;
@@ -112,7 +156,9 @@ try {
                     throw new Error('setup_invalid_options');
             }
             const packageRoot = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../' : '../../', import.meta.url));
-            const result = command === 'setup' ? setupHosts({ clients, mode, automatic, packageRoot }) : removeSetup({ clients });
+            if ((migrate && (clients.length !== 1 || automatic || seen.has('--mode'))) || ((dryRun || includeExisting) && !migrate))
+                throw new Error('setup_invalid_options');
+            const result = migrate ? migrateLauncher({ clients, packageRoot }, dryRun, includeExisting) : command === 'setup' ? setupHosts({ clients, mode, automatic, packageRoot }) : removeSetup({ clients });
             output(result);
             if (result.status === 'partial' && !automatic)
                 process.exitCode = 1;
@@ -168,7 +214,17 @@ catch (error) {
     const message = error instanceof Error ? error.message : undefined;
     const configCode = [caughtCode, message].find(value => typeof value === 'string' && safeConfigurationCodes.includes(value));
     const setCodes = ['set_environment_key_unsupported', 'set_invalid_options', 'set_value_too_large', 'set_interactive_input_required', 'set_input_cancelled'];
-    const code = command === 'set' ? (setCodes.includes(message ?? '') ? message : 'set_failed') : command === 'report' ? (caughtCode && codes.includes(caughtCode) ? caughtCode : 'report_failed') : configCode ?? 'operation_failed';
+    const code = command === 'update' ? (message === 'update_invalid_options' ? message : 'update_failed') : command === 'set' ? (setCodes.includes(message ?? '') ? message : 'set_failed') : command === 'report' ? (caughtCode && codes.includes(caughtCode) ? caughtCode : 'report_failed') : configCode ?? 'operation_failed';
     process.stderr.write('aptly: ' + code + '\n');
     process.exitCode = 1;
 }
+finally {
+    if (!process.exitCode) {
+        try {
+            const hint = await updateNotification({ command, args, env: process.env, stdinIsTTY: !!process.stdin.isTTY, stderrIsTTY: !!process.stderr.isTTY, stdoutIsTTY: !!process.stdout.isTTY, currentVersion: VERSION });
+            if (hint)
+                process.stderr.write(hint + '\n');
+        }
+        catch { /* Optional update hints cannot fail a successful command. */ }
+    }
+}

package/dist/src/core.d.ts

@@ -23,6 +23,7 @@ export declare class Router {
     ledgerPath: string | undefined;
     state: LedgerState;
     active: number;
+    private heldLedgerLock;
     constructor({ policy, provider, ledgerPath }?: RouterOptions);
     capabilities(): {
         policy_version: string;

package/dist/src/core.js

@@ -1,7 +1,8 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { openSync, closeSync, readFileSync, writeFileSync, renameSync, unlinkSync, lstatSync, chmodSync } from 'node:fs';
 import { isRecord, errorCode } from './types.js';
 import { builtInProfiles, resolveCatalog, isSupportedProfile } from './catalog.js';
+import { acquireLedgerLock } from './ledger-lock.js';
 const defaultCatalog = resolveCatalog({});
 export const defaultPolicy = Object.freeze({
     version: 'aptly-v010', catalog_version: defaultCatalog.version, max_summary_bytes: 4000,
@@ -66,6 +67,7 @@ export class Router {
     ledgerPath;
     state;
     active;
+    heldLedgerLock;
     constructor({ policy = defaultPolicy, provider, ledgerPath } = {}) {
         this.policy = clone(policy);
         const integerCaps = { max_summary_bytes: 64000, max_concurrency: 16, max_daily_calls: 100000, max_total_calls: 1000000, timeout_ms: 60000 };
@@ -123,6 +125,7 @@ export class Router {
     load() {
         if (!this.ledgerPath)
             return;
+        this.heldLedgerLock?.assertHeld();
         try {
             const stat = lstatSync(this.ledgerPath);
             if (!stat.isFile() || stat.isSymbolicLink())
@@ -158,13 +161,15 @@ export class Router {
     save() {
         if (!this.ledgerPath)
             return;
-        const tmp = `${this.ledgerPath}.write-${process.pid}`;
+        this.heldLedgerLock?.assertHeld();
+        const tmp = `${this.ledgerPath}.write-${randomUUID()}`;
         let fd;
         try {
             fd = openSync(tmp, 'wx', 0o600);
             writeFileSync(fd, JSON.stringify(this.state));
             closeSync(fd);
             fd = undefined;
+            this.heldLedgerLock?.assertHeld();
             renameSync(tmp, this.ledgerPath);
         }
         finally {
@@ -228,12 +233,13 @@ export class Router {
         let lock;
         if (this.ledgerPath) {
             try {
-                lock = openSync(`${this.ledgerPath}.lock`, 'wx', 0o600);
+                lock = acquireLedgerLock(this.ledgerPath);
             }
-            catch {
-                return this.result('unavailable', 'ledger_locked');
+            catch (error) {
+                return this.result('unavailable', errorCode(error) === 'ledger_locked' ? 'ledger_locked' : 'ledger_error');
             }
         }
+        this.heldLedgerLock = lock;
         this.active++;
         try {
             this.load();
@@ -308,7 +314,7 @@ export class Router {
             }
             catch (e) {
                 // A failed transport can have consumed a paid call. Preserve its unknown marker.
-                const allowed = ['timeout', 'refused', 'truncated', 'invalid_json', 'unauthorized', 'rate_limited', 'network'];
+                const allowed = ['timeout', 'refused', 'truncated', 'invalid_json', 'unauthorized', 'rate_limited', 'network', 'ledger_error'];
                 const code = errorCode(e);
                 return this.result('unavailable', code !== undefined && allowed.includes(code) ? code : 'provider_error', { latency_ms: latency() });
             }
@@ -321,12 +327,12 @@ export class Router {
         }
         finally {
             this.active--;
+            this.heldLedgerLock = undefined;
             if (lock !== undefined) {
-                closeSync(lock);
                 try {
-                    unlinkSync(`${this.ledgerPath}.lock`);
+                    lock.release();
                 }
-                catch { }
+                catch { /* Never unlink a persistent OS-owned gate. */ }
             }
         }
     }

package/dist/src/credential-setup.d.ts

@@ -11,4 +11,8 @@ export interface CredentialBackend {
     }): void;
 }
 /** Key bytes enter the OS store only; host files receive nonsecret references. */
+export declare function prepareApiKey(options?: SetupOptions): {
+    result: SetupResult;
+    apply(value: string, backend?: CredentialBackend): SetupResult;
+};
 export declare function setApiKey(value: string, options?: SetupOptions, backend?: CredentialBackend): SetupResult;

package/dist/src/credential-setup.js

@@ -1,7 +1,18 @@
 import { loadSecret, storeSecret, deleteSecret } from './secret-store.js';
-import { setCredentialReference } from './setup.js';
+import { prepareCredentialReference } from './setup.js';
 /** Restore once, then verify even if the restore's acknowledgement was lost. */
-function restore(previous, account, backend) {
+function restore(previous, attemptedValue, account, backend) {
+    // Do not overwrite an observed concurrent credential change or an unreadable value.
+    try {
+        const current = backend.loadSecret({ account });
+        if (current === previous)
+            return true;
+        if (current !== attemptedValue)
+            return false;
+    }
+    catch {
+        return false;
+    }
     try {
         if (previous === null)
             backend.deleteSecret({ account });
@@ -17,40 +28,62 @@ function restore(previous, account, backend) {
     }
 }
 /** Key bytes enter the OS store only; host files receive nonsecret references. */
-export function setApiKey(value, options = {}, backend = { loadSecret, storeSecret, deleteSecret }) {
+export function prepareApiKey(options = {}) {
     const clients = [...new Set(options.clients ?? ['codex', 'claude'])];
     if (clients.some(c => c !== 'codex' && c !== 'claude'))
-        return { status: 'partial', clients: [] };
-    if (!/^sk-[A-Za-z0-9_-]{12,}$/.test(value) || Buffer.byteLength(value) > 8192)
-        return { status: 'partial', clients: clients.map(client => ({ client, status: 'error', codes: ['credential_value_invalid'] })) };
-    const results = [];
-    for (const client of clients) {
-        const account = `${client}:OPENAI_API_KEY`;
-        let previous = null, attempted = false;
-        try {
-            previous = backend.loadSecret({ account });
-            // A timeout/process/output error may occur after the OS committed a write.
-            attempted = true;
-            backend.storeSecret(value, { account });
-            const configured = setCredentialReference({ ...options, clients: [client] });
-            const result = configured.clients[0];
-            if (!result || result.status === 'error' || result.status === 'skipped') {
-                const recovered = restore(previous, account, backend);
-                const failed = result ?? { client, status: 'error', codes: ['credential_configuration_failed'] };
-                results.push(recovered ? failed : { ...failed, status: 'error', codes: [...failed.codes, 'credential_rollback_failed'] });
+        throw new Error('set_invalid_options');
+    const plans = clients.map(client => prepareCredentialReference(options, client));
+    const result = { status: plans.some(p => p.result.status === 'error') ? 'partial' : 'complete', clients: plans.map(p => p.result) };
+    let used = false;
+    return { result, apply(value, backend = { loadSecret, storeSecret, deleteSecret }) {
+            if (used)
+                return { status: 'partial', clients: clients.map(client => ({ client, status: 'error', codes: ['credential_plan_consumed'] })) };
+            used = true;
+            if (!/^sk-[A-Za-z0-9_-]{12,}$/.test(value) || Buffer.byteLength(value) > 8192)
+                return { status: 'partial', clients: clients.map(client => ({ client, status: 'error', codes: ['credential_value_invalid'] })) };
+            const results = [];
+            for (const plan of plans) {
+                const client = plan.result.client;
+                const checked = plan.check();
+                if (checked.status === 'error') {
+                    results.push(checked);
+                    continue;
+                }
+                const account = `${client}:OPENAI_API_KEY`;
+                let previous = null, attempted = false;
+                try {
+                    previous = backend.loadSecret({ account });
+                    const rechecked = plan.check();
+                    if (rechecked.status === 'error') {
+                        results.push(rechecked);
+                        continue;
+                    }
+                    // A timeout/process/output error may occur after the OS committed a write.
+                    attempted = true;
+                    backend.storeSecret(value, { account });
+                    const result = plan.commit();
+                    if (!result || result.status === 'error' || result.status === 'skipped') {
+                        const recovered = restore(previous, value, account, backend);
+                        const failed = result ?? { client, status: 'error', codes: ['credential_configuration_failed'] };
+                        results.push(recovered ? failed : { ...failed, status: 'error', codes: [...failed.codes, 'credential_rollback_failed'] });
+                    }
+                    else
+                        results.push({ ...result, codes: [...result.codes, 'credential_stored_in_os', 'mcp_restart_required'] });
+                }
+                catch (error) {
+                    const recovered = !attempted || restore(previous, value, account, backend);
+                    const allowed = ['secure_store_invalid_options', 'secure_store_invalid_value', 'secure_store_unavailable', 'secure_store_timeout', 'secure_store_failed', 'secure_store_cancelled', 'secure_store_denied', 'secure_store_locked', 'secure_store_unsupported_platform'];
+                    const code = error instanceof Error && allowed.includes(error.message) ? error.message : 'credential_store_failed';
+                    results.push({ client, status: 'error', codes: [code, ...(recovered ? [] : ['credential_rollback_failed'])] });
+                }
+                finally {
+                    previous = null;
+                }
             }
-            else
-                results.push({ ...result, codes: [...result.codes, 'credential_stored_in_os', 'mcp_restart_required'] });
+            return { status: results.some(r => r.status === 'error') ? 'partial' : 'complete', clients: results };
         }
-        catch (error) {
-            const recovered = !attempted || restore(previous, account, backend);
-            const allowed = ['secure_store_invalid_options', 'secure_store_invalid_value', 'secure_store_unavailable', 'secure_store_timeout', 'secure_store_failed', 'secure_store_cancelled', 'secure_store_denied', 'secure_store_locked', 'secure_store_unsupported_platform'];
-            const code = error instanceof Error && allowed.includes(error.message) ? error.message : 'credential_store_failed';
-            results.push({ client, status: 'error', codes: [code, ...(recovered ? [] : ['credential_rollback_failed'])] });
-        }
-        finally {
-            previous = null;
-        }
-    }
-    return { status: results.some(r => r.status === 'error') ? 'partial' : 'complete', clients: results };
+    };
+}
+export function setApiKey(value, options = {}, backend = { loadSecret, storeSecret, deleteSecret }) {
+    return prepareApiKey(options).apply(value, backend);
 }

package/dist/src/ledger-lock.d.ts

@@ -0,0 +1,8 @@
+export interface LedgerLock {
+    /** lstat-only while held: never open/read/close the canonical SQLite file. */
+    assertHeld(): void;
+    /** Roll back and close this connection. Never unlink the persistent gate. */
+    release(): void;
+}
+/** Local, hard-link-capable filesystems only; no PID or stale-age recovery. */
+export declare function acquireLedgerLock(ledgerPath: string): LedgerLock;