aptly 0.1.0 → 0.1.2

package/README.en.md

@@ -1,23 +1,40 @@
+<div align="center">
+
 # Aptly
 
+[![npm version](https://img.shields.io/npm/v/aptly)](https://www.npmjs.com/package/aptly)
+[![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, powered by the OpenAI Decisions API.**
+
 [한국어](README.md) · **English** · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
 
 **A local MCP server that selects Claude Code and Codex subagent models and reasoning effort to suit the task.**
 
+</div>
+
 Aptly classifies a minimal task summary with the OpenAI Decisions API and recommends an allowlisted execution profile. Its installed Hook can automatically select defaults for fresh, general-purpose subagents without explicit choices. The host retains control of execution and permissions.
 
+Our own tests showed **about 52–58% lower API-equivalent costs**. See the [test conditions and detailed results](docs/guide/en.md#cost-benchmark).
+
 ## Quick start
 
-Use Node.js **24 or later** and Claude Code or Codex. This is an **MIT-licensed local 0.1.0 package draft**, not a release published to the npm registry. Replace the archive path below with the actual reviewed archive.
+Requires Node.js **24 or later** and Claude Code or Codex. Install the latest stable version globally with these commands.
 
 ```sh
-npm install --prefix ./aptly-local /absolute/path/aptly-0.1.0.tgz
-./aptly-local/node_modules/.bin/aptly setup --client all --mode defaults
+npm install -g aptly@latest
+aptly setup --client all --mode defaults
+aptly --version
 ```
 
+Check the installed version with `aptly --version`.
+
+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.
 
-Pass the classification key, `OPENAI_API_KEY`, to the MCP process through a secure execution environment. Do not put it in command arguments, requests, configuration JSON, or the repository. Restart the host or MCP server, then **review and trust the new Hook through `/hooks` in Codex**. See [installation, keys, and registration](docs/guide/en.md#installation).
+Store the classification key, `OPENAI_API_KEY`, in the OS credential store using the hidden prompt in `aptly set env OPENAI_API_KEY`, or pass it to the MCP process through a secure execution environment. Do not put it in command arguments, requests, configuration JSON, or the repository. Restart the host or MCP server, then **review and trust the new Hook through `/hooks` in Codex**. See [installation, keys, and registration](docs/guide/en.md#installation).
 
 ## Usage modes
 
@@ -31,8 +48,9 @@ Automatic selection targets Codex calls with `fork_turns: "none"` and Claude Cod
 
 ## Documentation
 
+- [CLI configuration](docs/guide/en.md#configure-with-the-cli)
 - [User guide](docs/guide/en.md): installation and removal, keys, Hooks, direct recommendations, and error recovery
-- [Installation and removal](docs/guide/en.md#installation): local archives, host registration, restarting, and trust review
+- [Installation and removal](docs/guide/en.md#installation): global npm installation, host registration, restarting, and trust review
 - [Models and environment variables](docs/guide/en.md#models-and-environment-variables): six default profiles and candidate configuration
 - [Providing context](docs/guide/en.md#providing-context): encrypted messages and repository URL limitations
 - [Cost benchmark](docs/guide/en.md#cost-benchmark): tokens, converted costs, and measurement scope for a README translation review

package/README.ja.md

@@ -1,23 +1,40 @@
+<div align="center">
+
 # Aptly
 
+[![npm version](https://img.shields.io/npm/v/aptly)](https://www.npmjs.com/package/aptly)
+[![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, powered by the OpenAI Decisions API.**
+
 [한국어](README.md) · [English](README.en.md) · [简体中文](README.zh-CN.md) · **日本語**
 
 **タスクに適した Claude Code・Codex のサブエージェント用モデルと effort を選ぶローカル MCP です。**
 
+</div>
+
 Aptly は必要最小限のタスク要約を OpenAI Decisions API で分類し、あらかじめ許可された実行プロファイルを推薦します。インストールした Hook は、明示的な指定のない新しい汎用サブエージェントのデフォルト値を自動で選択できます。サブエージェントの実行と権限に関する判断は、既存のホストが行います。
 
+独自テストでは、**API 換算コストが約 52～58% 減少しました**。[測定条件と詳細結果](docs/guide/ja.md#費用実測)をご覧ください。
+
 ## クイックスタート
 
-Node.js **24 以上**と Claude Code または Codex が必要です。現在は **MIT ライセンスの 0.1.0 ローカルパッケージ案**で、npm registry にはまだ公開していません。確認済みのアーカイブの実際のパスに置き換えてインストールしてください。
+Node.js **24 以上**と Claude Code または Codex が必要です。以下のコマンドで最新の安定版をグローバルインストールしてください。
 
 ```sh
-npm install --prefix ./aptly-local /absolute/path/aptly-0.1.0.tgz
-./aptly-local/node_modules/.bin/aptly setup --client all --mode defaults
+npm install -g aptly@latest
+aptly setup --client all --mode defaults
+aptly --version
 ```
 
+`aptly --version` でインストール済みのバージョンを確認してください。
+
+アップグレード前に、関連するホスト・MCP・CLI の全プロセスを停止し、[インストールとアップグレードの案内](docs/guide/ja.md#インストール)で台帳の移行手順を確認してください。
+
 インストール時の `postinstall` は、既存のホスト設定ディレクトリに MCP と `PreToolUse` Hook を登録します。自動登録をスキップした場合や、ホストに設定ディレクトリがまだない場合も、`setup` を明示的に実行して登録できます。他の既存設定・Hook と、既存の Aptly の実行コマンド・環境は保持します。
 
-分類用の `OPENAI_API_KEY` は、安全な実行環境から MCP プロセスに渡してください。キーをコマンドライン・リクエスト・設定 JSON・リポジトリに記載しないでください。ホストまたは MCP を再起動した後、**Codex では `/hooks` で新しい Hook を確認し、信頼を承認**してください。[インストール・キー・登録の詳細](docs/guide/ja.md#インストール)を確認してください。
+分類用の `OPENAI_API_KEY` は、`aptly set env OPENAI_API_KEY` の非表示入力で OS の資格情報ストアに保存するか、安全な実行環境から MCP プロセスに渡してください。キーをコマンドライン・リクエスト・設定 JSON・リポジトリに記載しないでください。ホストまたは MCP を再起動した後、**Codex では `/hooks` で新しい Hook を確認し、信頼を承認**してください。[インストール・キー・登録の詳細](docs/guide/ja.md#インストール)を確認してください。
 
 ## 使用方法
 
@@ -31,8 +48,9 @@ npm install --prefix ./aptly-local /absolute/path/aptly-0.1.0.tgz
 
 ## ドキュメント
 
+- [CLI 設定](docs/guide/ja.md#cli-による設定)
 - [使用ガイド](docs/guide/ja.md): インストール・削除、キー、Hook、直接推薦、エラー復旧
-- [インストール・削除](docs/guide/ja.md#インストール): ローカルアーカイブ、ホスト登録、再起動と信頼の承認
+- [インストール・削除](docs/guide/ja.md#インストール): npm のグローバルインストール、ホスト登録、再起動と信頼の承認
 - [モデルと環境変数](docs/guide/ja.md#モデルと環境変数): 6 つのデフォルトプロファイルと候補の設定
 - [コンテキストの提供](docs/guide/ja.md#コンテキストの提供): 暗号化されたメッセージとリポジトリ URL の制約
 - [費用実測](docs/guide/ja.md#費用実測): README 翻訳レビューのトークン・換算費用と測定範囲

package/README.md

@@ -1,23 +1,40 @@
+<div align="center">
+
 # Aptly
 
+[![npm version](https://img.shields.io/npm/v/aptly)](https://www.npmjs.com/package/aptly)
+[![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, powered by the OpenAI Decisions API.**
+
 **한국어** · [English](README.en.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
 
 **작업에 맞는 Claude Code·Codex 서브에이전트 모델과 effort를 선택하는 로컬 MCP입니다.**
 
+</div>
+
 Aptly는 최소한의 작업 요약을 OpenAI Decisions API로 분류하고 허용된 실행 프로필을 추천합니다. 설치한 Hook은 명시 선택이 없는 새 일반 서브에이전트의 기본값을 자동으로 선택할 수 있습니다. 실제 실행과 권한 결정은 기존 호스트가 담당합니다.
 
+자체 테스트에서 **API 환산 비용이 약 52~58% 감소했습니다**. [측정 조건과 상세 결과](docs/guide/ko.md#비용-실측)를 확인하세요.
+
 ## 빠른 시작
 
-Node.js **24 이상**과 Claude Code 또는 Codex가 필요합니다. 현재는 **MIT 라이선스의 0.1.0 로컬 패키지 초안**이며 npm 레지스트리에 게시하지 않았습니다. 검토한 아카이브의 실제 경로로 바꿔 설치하십시오.
+Node.js **24 이상**과 Claude Code 또는 Codex가 필요합니다. 다음 명령으로 최신 안정 버전을 전역 설치하십시오.
 
 ```sh
-npm install --prefix ./aptly-local /absolute/path/aptly-0.1.0.tgz
-./aptly-local/node_modules/.bin/aptly setup --client all --mode defaults
+npm install -g aptly@latest
+aptly setup --client all --mode defaults
+aptly --version
 ```
 
+`aptly --version`으로 설치된 버전을 확인하십시오.
+
+업그레이드 전에는 관련 호스트·MCP·CLI 프로세스를 모두 중지하고 [설치·업그레이드 안내](docs/guide/ko.md#설치)의 원장 전환 절차를 확인하십시오.
+
 설치 시 `postinstall`은 기존 호스트 설정 디렉터리에 MCP와 `PreToolUse` Hook을 등록합니다. 명시적인 `setup`은 자동 등록을 건너뛰었거나 아직 설정 디렉터리가 없는 호스트에도 사용할 수 있습니다. 기존 다른 설정·Hook과 기존 Aptly 실행 명령·환경은 보존합니다.
 
-분류용 `OPENAI_API_KEY`는 안전한 실행 환경에서 MCP 프로세스에 전달하십시오. 키를 명령행·요청·설정 JSON·저장소에 기록하지 마십시오. 호스트 또는 MCP를 재시작한 뒤, **Codex에서는 `/hooks`에서 새 Hook을 검토하고 신뢰를 승인하십시오.** [설치·키·등록 상세](docs/guide/ko.md#설치)를 참고하십시오.
+분류용 `OPENAI_API_KEY`는 `aptly set env OPENAI_API_KEY`의 숨김 입력으로 OS 자격 저장소에 보관하거나 안전한 실행 환경에서 MCP 프로세스에 전달하십시오. 키를 명령행·요청·설정 JSON·저장소에 기록하지 마십시오. 호스트 또는 MCP를 재시작한 뒤, **Codex에서는 `/hooks`에서 새 Hook을 검토하고 신뢰를 승인하십시오.** [설치·키·등록 상세](docs/guide/ko.md#설치)를 참고하십시오.
 
 ## 사용 방식
 
@@ -31,8 +48,9 @@ npm install --prefix ./aptly-local /absolute/path/aptly-0.1.0.tgz
 
 ## 문서
 
+- [CLI 설정](docs/guide/ko.md#cli로-설정하기)
 - [사용 가이드](docs/guide/ko.md): 설치·제거, 키, Hook, 직접 추천, 오류 복구
-- [설치·제거](docs/guide/ko.md#설치): 로컬 아카이브, 호스트 등록, 재시작과 신뢰 승인
+- [설치·제거](docs/guide/ko.md#설치): npm 전역 설치, 호스트 등록, 재시작과 신뢰 승인
 - [모델과 환경변수](docs/guide/ko.md#모델과-환경변수): 여섯 기본 프로필과 후보 설정
 - [맥락 전달](docs/guide/ko.md#맥락-전달): 암호화된 메시지와 저장소 URL의 한계
 - [비용 실측](docs/guide/ko.md#비용-실측): README 번역 검토의 토큰·환산 비용과 측정 범위

package/README.zh-CN.md

@@ -1,23 +1,40 @@
+<div align="center">
+
 # Aptly
 
+[![npm version](https://img.shields.io/npm/v/aptly)](https://www.npmjs.com/package/aptly)
+[![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, powered by the OpenAI Decisions API.**
+
 [한국어](README.md) · [English](README.en.md) · **简体中文** · [日本語](README.ja.md)
 
 **用于为 Claude Code 和 Codex 子代理选择合适模型与推理强度（effort）的本地 MCP 服务器。**
 
+</div>
+
 Aptly 使用 OpenAI Decisions API 对简要任务摘要进行分类，并推荐允许使用的执行配置。安装 Hook 后，可为未明确指定配置的新建通用子代理自动选择默认值。实际执行与权限决策仍由宿主（Claude Code 或 Codex）负责。
 
+在我们的测试中，**API 折算成本降低了约 52%～58%**。详见[测试条件与详细结果](docs/guide/zh-CN.md#成本实测)。
+
 ## 快速开始
 
-需要 Node.js **24 或更高版本**，以及 Claude Code 或 Codex。目前是**采用 MIT 许可证的 0.1.0 本地软件包草案**，尚未发布到 npm registry。请将示例路径替换为已审核归档文件的实际路径。
+需要 Node.js **24 或更高版本**以及 Claude Code 或 Codex。请使用以下命令全局安装最新稳定版。
 
 ```sh
-npm install --prefix ./aptly-local /absolute/path/aptly-0.1.0.tgz
-./aptly-local/node_modules/.bin/aptly setup --client all --mode defaults
+npm install -g aptly@latest
+aptly setup --client all --mode defaults
+aptly --version
 ```
 
+请使用 `aptly --version` 确认已安装的版本。
+
+升级前，请停止所有相关宿主、MCP 和 CLI 进程，并查看[安装与升级指南](docs/guide/zh-CN.md#安装)中的账本迁移步骤。
+
 安装时的 `postinstall` 会在现有宿主配置目录中注册 MCP 和 `PreToolUse` Hook。如果跳过了自动注册，或宿主尚无配置目录，也可以显式运行 `setup`。其他现有配置与 Hook，以及 Aptly 原有的启动命令和环境均会保留。
 
-请通过安全的运行环境，将分类用的 `OPENAI_API_KEY` 传递给 MCP 进程。不要将密钥写入命令行、请求、配置 JSON 或代码仓库。重启宿主或 MCP 后，**请在 Codex 的 `/hooks` 中审核新 Hook 并批准信任**。详见[安装、密钥与注册](docs/guide/zh-CN.md#安装)。
+请通过 `aptly set env OPENAI_API_KEY` 的隐藏输入，将分类用的 `OPENAI_API_KEY` 存入系统凭据存储，或通过安全的运行环境传递给 MCP 进程。不要将密钥写入命令行、请求、配置 JSON 或代码仓库。重启宿主或 MCP 后，**请在 Codex 的 `/hooks` 中审核新 Hook 并批准信任**。详见[安装、密钥与注册](docs/guide/zh-CN.md#安装)。
 
 ## 使用方式
 
@@ -31,8 +48,9 @@ npm install --prefix ./aptly-local /absolute/path/aptly-0.1.0.tgz
 
 ## 文档
 
+- [CLI 配置](docs/guide/zh-CN.md#使用-cli-设置)
 - [使用指南](docs/guide/zh-CN.md)：安装与移除、密钥、Hook、直接推荐、错误恢复
-- [安装与移除](docs/guide/zh-CN.md#安装)：本地归档、宿主注册、重启与信任批准
+- [安装与移除](docs/guide/zh-CN.md#安装)：npm 全局安装、宿主注册、重启与信任批准
 - [模型与环境变量](docs/guide/zh-CN.md#模型与环境变量)：六个默认配置与候选设置
 - [提供上下文](docs/guide/zh-CN.md#提供上下文)：加密消息与仓库 URL 的限制
 - [成本实测](docs/guide/zh-CN.md#成本实测)：README 翻译审阅的 token、换算成本与测量范围

package/dist/bin/aptly.js

@@ -9,12 +9,14 @@ 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 } from '../src/setup.js';
+import { setupHosts, removeSetup, setDefaults, setEnvironment, configurableEnvironmentKeys, migrateLauncher } from '../src/setup.js';
+import { readEnvironmentValue } from '../src/cli-input.js';
+import { prepareApiKey } from '../src/credential-setup.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  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\nSet OPENAI_API_KEY only in the MCP environment. Paid 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  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 === '--version')
         process.stdout.write(VERSION + '\n');
@@ -35,19 +37,92 @@ try {
             throw Object.assign(new Error('report_invalid_options'), { code: 'report_invalid_options' });
         output(exportDiagnosticReport({ diagnostic: collectDiagnostics(), ...options }));
     }
+    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 | --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;
+            let start = 1;
+            if (action === 'env') {
+                key = args[1];
+                start = 2;
+                if (!key || (key !== 'OPENAI_API_KEY' && !configurableEnvironmentKeys.includes(key)))
+                    throw new Error('set_environment_key_unsupported');
+            }
+            else if (action !== 'default')
+                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;
+                }
+                if (flag === '--client' && ['codex', 'claude', 'all'].includes(args[i + 1])) {
+                    const v = args[++i];
+                    clients = v === 'all' ? ['codex', 'claude'] : [v];
+                }
+                else
+                    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 = '';
+            if (credential && (checkOnly || credential.result.status === 'partial')) {
+                output(credential.result);
+                if (credential.result.status === 'partial')
+                    process.exitCode = 1;
+            }
+            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 [--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;
             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 === '--dry-run' && command === 'setup') {
+                    dryRun = true;
+                    continue;
+                }
                 if (flag === '--automatic' && command === 'setup') {
                     automatic = true;
                     continue;
@@ -61,7 +136,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 && !migrate))
+                throw new Error('setup_invalid_options');
+            const result = migrate ? migrateLauncher({ clients, packageRoot }, dryRun) : command === 'setup' ? setupHosts({ clients, mode, automatic, packageRoot }) : removeSetup({ clients });
             output(result);
             if (result.status === 'partial' && !automatic)
                 process.exitCode = 1;
@@ -70,8 +147,8 @@ try {
     else if (command === 'serve' && args.length === 0)
         await serve();
     else if ((command === 'capabilities' || command === 'catalog') && args.length === 0) {
-        const { router, mode, modelInfo, disabledClients } = runtime();
-        output({ ...router.capabilities(), provider: mode, model_information: { status: modelInfo.status, account_access_verified: false }, disabled_clients: disabledClients });
+        const { router, mode, modelInfo, credentialStatus, disabledClients } = runtime();
+        output({ ...router.capabilities(), provider: mode, credential_status: credentialStatus, model_information: { status: modelInfo.status, account_access_verified: false }, disabled_clients: disabledClients });
     }
     else if (command === 'catalog' && args.length === 3 && args[0] === 'refresh' && args[1] === '--output') {
         const snapshot = await fetchModelInfo();
@@ -116,7 +193,8 @@ catch (error) {
     const safeConfigurationCodes = ['catalog_configuration_invalid', 'catalog_configuration_conflict', 'catalog_environment_typo', 'catalog_facts_invalid', 'model_info_fetch_failed', 'model_info_unavailable', 'model_info_invalid', 'model_info_output_unavailable', 'model_info_path_invalid', 'model_info_refresh_failed', 'model_info_options_invalid', 'model_info_too_large', 'model_info_timeout', 'model_info_parse_failed', 'model_info_save_failed'];
     const message = error instanceof Error ? error.message : undefined;
     const configCode = [caughtCode, message].find(value => typeof value === 'string' && safeConfigurationCodes.includes(value));
-    const code = command === 'report' ? (caughtCode && codes.includes(caughtCode) ? caughtCode : 'report_failed') : configCode ?? 'operation_failed';
+    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';
     process.stderr.write('aptly: ' + code + '\n');
     process.exitCode = 1;
 }

package/dist/src/cli-input.d.ts

@@ -0,0 +1,5 @@
+/** Values never appear in argv, echoed terminal input, diagnostics or temporary files. */
+export declare function readEnvironmentValue({ key, fromStdin }: {
+    key: string;
+    fromStdin?: boolean;
+}): Promise<string>;

package/dist/src/cli-input.js

@@ -0,0 +1,49 @@
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { StringDecoder } from 'node:string_decoder';
+const fail = (code) => new Error(code);
+/** Values never appear in argv, echoed terminal input, diagnostics or temporary files. */
+export async function readEnvironmentValue({ key, fromStdin = false }) {
+    if (fromStdin) {
+        const decoder = new StringDecoder('utf8');
+        let value = '', bytesRead = 0;
+        for await (const chunk of process.stdin) {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            bytesRead += bytes.length;
+            if (bytesRead > 8192)
+                throw fail('set_value_too_large');
+            value += decoder.write(bytes);
+        }
+        value += decoder.end();
+        if (Buffer.byteLength(value) > 8192)
+            throw fail('set_value_too_large');
+        return value.replace(/\r?\n$/, '');
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw fail('set_interactive_input_required');
+    const silent = new Writable({ write(_chunk, _encoding, done) { done(); } });
+    const rl = createInterface({ input: process.stdin, output: silent, terminal: true });
+    process.stdout.write(`Value for ${key} (input hidden): `);
+    try {
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const cancel = () => { if (!settled) {
+                settled = true;
+                reject(fail('set_input_cancelled'));
+            } };
+            rl.once('SIGINT', () => { cancel(); rl.close(); });
+            rl.once('close', cancel);
+            rl.question('', value => {
+                settled = true;
+                if (Buffer.byteLength(value) > 8192)
+                    reject(fail('set_value_too_large'));
+                else
+                    resolve(value);
+            });
+        });
+    }
+    finally {
+        rl.close();
+        process.stdout.write('\n');
+    }
+}

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();
@@ -258,6 +264,15 @@ export class Router {
                 return complete(this.result('keep_current', 'preserved_constraints'));
             if (!req.task.context_sufficient)
                 return complete(this.result('needs_context', 'insufficient_context'));
+            // Known local failures precede reservation. Do not cache them: correcting
+            // configuration must allow the same ID to be tried without ledger edits.
+            // Never infer this from a transport exception (including HTTP 401/403).
+            try {
+                this.provider.preflight?.();
+            }
+            catch (e) {
+                return this.result('unavailable', errorCode(e) === 'unauthorized' ? 'unauthorized' : 'provider_error');
+            }
             const day = new Date().toISOString().slice(0, 10);
             if (this.state.calls >= this.policy.max_total_calls || (this.state.days[day] ?? 0) >= this.policy.max_daily_calls || this.state.estimated_usd + this.policy.estimated_call_usd > this.policy.max_estimated_usd + 1e-12)
                 return complete(this.result('unavailable', 'budget_exhausted'));
@@ -299,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() });
             }
@@ -312,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

@@ -0,0 +1,18 @@
+import type { SetupOptions, SetupResult } from './setup.ts';
+export interface CredentialBackend {
+    loadSecret(options: {
+        account: string;
+    }): string | null;
+    storeSecret(value: string, options: {
+        account: string;
+    }): void;
+    deleteSecret(options: {
+        account: string;
+    }): 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;