@itpay/cli 2.1.44 → 2.1.45

package/dist/src/state/device_key.js

@@ -0,0 +1,69 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID } from "node:crypto";
+import { constants, closeSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+function invalid(code) { return Object.assign(new Error(code), { code }); }
+export function readDeviceKey(path) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw invalid("DEVICE_KEY_INVALID_FILE");
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const opened = fstatSync(fd);
+        if (stat.dev !== opened.dev || stat.ino !== opened.ino)
+            throw invalid("DEVICE_KEY_CHANGED");
+        const key = createPrivateKey(readFileSync(fd, "utf8"));
+        if (key.asymmetricKeyType !== "ed25519")
+            throw invalid("DEVICE_KEY_INVALID");
+        return key;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function deviceKeyThumbprint(key) {
+    return createHash("sha256").update(createPublicKey(key).export({ format: "der", type: "spki" })).digest("hex");
+}
+// Only a complete key is published. EEXIST means a competing creator won;
+// every caller uses the canonical file, never its unpublished generated key.
+export function createDeviceKey(path, existingIdentity) {
+    const existing = readDeviceKey(path);
+    if (existing)
+        return existing;
+    if (existingIdentity)
+        throw invalid("DEVICE_KEY_MISSING");
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temp = `${path}.${randomUUID()}.tmp`;
+    const key = generateKeyPairSync("ed25519").privateKey;
+    writeFileSync(temp, key.export({ format: "pem", type: "pkcs8" }), { flag: "wx", mode: 0o600 });
+    let canonicalPublished = false;
+    try {
+        try {
+            linkSync(temp, path);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const canonical = readDeviceKey(path);
+        if (!canonical)
+            throw invalid("DEVICE_KEY_MISSING");
+        canonicalPublished = true;
+        return canonical;
+    }
+    finally {
+        try {
+            unlinkSync(temp);
+        }
+        catch (error) {
+            throw Object.assign(error instanceof Error ? error : new Error("Key temporary cleanup failed"), { deviceStateOperation: "cleanup_private_key_temporary", canonicalKeyPublished: canonicalPublished });
+        }
+    }
+}

package/dist/src/state/device_session_cache.js

@@ -0,0 +1,203 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants, closeSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+function invalid(code) { return Object.assign(new Error(code), { code }); }
+function readRegular(path) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw invalid("DEVICE_CACHE_INVALID_FILE");
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const opened = fstatSync(fd);
+        // Concurrent atomic replacement is normal for reconstructible caches.
+        // Read the complete opened snapshot; generation validation decides freshness.
+        // O_NOFOLLOW and fstat still reject symlinks and non-regular opened files.
+        if (!opened.isFile())
+            throw invalid("DEVICE_CACHE_INVALID_FILE");
+        return readFileSync(fd, "utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function writeComplete(path, text, createOnly) {
+    const temp = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(temp, text, { flag: "wx", mode: 0o600 });
+    try {
+        if (createOnly) {
+            try {
+                linkSync(temp, path);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    return false;
+                throw error;
+            }
+        }
+        else {
+            readRegular(path); // Refuse an existing symlink or unexpected file.
+            renameSync(temp, path);
+        }
+        return true;
+    }
+    finally {
+        try {
+            unlinkSync(temp);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+// Separate generation and session files: a late session write can never replace
+// the invalidation marker. Every reader checks the generation after reading.
+export class DeviceSessionCache {
+    directory;
+    context;
+    cachePath;
+    generationPath;
+    constructor(directory, context) {
+        this.directory = directory;
+        this.context = context;
+        const name = createHash("sha256").update(JSON.stringify([context.backend, context.agentType, context.keyThumbprint])).digest("hex");
+        this.cachePath = join(directory, `${name}.json`);
+        this.generationPath = join(directory, `${name}.generation`);
+    }
+    checkDirectory() {
+        let stat;
+        try {
+            stat = lstatSync(this.directory);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw invalid("DEVICE_CACHE_INVALID_FILE");
+    }
+    prepareDirectory() {
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        const stat = lstatSync(this.directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw invalid("DEVICE_CACHE_INVALID_FILE");
+    }
+    generation(create) {
+        this.checkDirectory();
+        let value = readRegular(this.generationPath);
+        if (value === undefined && create) {
+            if (readRegular(this.cachePath) !== undefined)
+                throw invalid("DEVICE_CACHE_GENERATION_MISSING");
+            this.prepareDirectory();
+            writeComplete(this.generationPath, this.newGeneration(), true);
+            value = readRegular(this.generationPath);
+        }
+        if (value === undefined)
+            return undefined;
+        let record;
+        try {
+            record = JSON.parse(value);
+        }
+        catch {
+            throw invalid("DEVICE_CACHE_GENERATION_INVALID");
+        }
+        if (!record || record.schemaVersion !== "itpay.device-generation.v1" || record.backend !== this.context.backend || record.agentType !== this.context.agentType || record.keyThumbprint !== this.context.keyThumbprint || typeof record.generation !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(record.generation))
+            throw invalid("DEVICE_CACHE_GENERATION_INVALID");
+        return record.generation;
+    }
+    newGeneration() {
+        return JSON.stringify({ schemaVersion: "itpay.device-generation.v1", ...this.context, generation: randomUUID() });
+    }
+    read() {
+        const before = this.generation(false);
+        const text = readRegular(this.cachePath);
+        if (text === undefined)
+            return undefined;
+        if (before === undefined)
+            throw invalid("DEVICE_CACHE_GENERATION_MISSING");
+        let record;
+        try {
+            record = JSON.parse(text);
+        }
+        catch {
+            throw invalid("DEVICE_CACHE_CORRUPT");
+        }
+        if (!record || record.schemaVersion !== "itpay.device-session.v1" || record.backend !== this.context.backend || record.agentType !== this.context.agentType || record.keyThumbprint !== this.context.keyThumbprint)
+            throw invalid("DEVICE_CACHE_CONTEXT_INVALID");
+        if (record.generation !== before || before !== this.generation(false))
+            return undefined;
+        const r = record.registration;
+        const session = r?.sessions?.[this.context.agentType];
+        if (!r || typeof r.deviceID !== "string" || typeof r.deviceKeyID !== "string" || typeof r.quotaLineageID !== "string" || typeof r.agentInstances?.[this.context.agentType] !== "string" || typeof session?.token !== "string" || typeof session.expiresAt !== "string" || !Number.isFinite(Date.parse(session.expiresAt)))
+            throw invalid("DEVICE_CACHE_CORRUPT");
+        return r;
+    }
+    registrationHint() {
+        this.checkDirectory();
+        const text = readRegular(this.cachePath);
+        if (text === undefined)
+            return undefined;
+        let record;
+        try {
+            record = JSON.parse(text);
+        }
+        catch {
+            throw invalid("DEVICE_CACHE_CORRUPT");
+        }
+        if (!record || record.schemaVersion !== "itpay.device-session.v1" || record.backend !== this.context.backend || record.agentType !== this.context.agentType || record.keyThumbprint !== this.context.keyThumbprint)
+            throw invalid("DEVICE_CACHE_CONTEXT_INVALID");
+        const r = record.registration;
+        if (!r || typeof r.deviceID !== "string" || typeof r.deviceKeyID !== "string" || typeof r.quotaLineageID !== "string" || typeof r.agentInstances?.[this.context.agentType] !== "string")
+            throw invalid("DEVICE_CACHE_CORRUPT");
+        return { deviceID: r.deviceID, deviceKeyID: r.deviceKeyID, quotaLineageID: r.quotaLineageID, agentInstances: { [this.context.agentType]: r.agentInstances[this.context.agentType] }, sessions: {} };
+    }
+    write(registration, generation) {
+        this.prepareDirectory();
+        writeComplete(this.cachePath, JSON.stringify({ schemaVersion: "itpay.device-session.v1", ...this.context, generation, registration }), false);
+    }
+    invalidate() {
+        this.generation(true);
+        writeComplete(this.generationPath, this.newGeneration(), false);
+    }
+}
+export function deviceCacheAgentTypes(directory, backend, keyThumbprint) {
+    let files;
+    try {
+        files = readdirSync(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const types = new Set();
+    for (const file of files.filter(name => /^[0-9a-f]{64}\.(json|generation)$/.test(name))) {
+        const text = readRegular(join(directory, file));
+        if (text === undefined)
+            continue;
+        const value = JSON.parse(text);
+        if (value?.backend !== backend || value?.keyThumbprint !== keyThumbprint)
+            continue;
+        const marker = file.endsWith(".generation");
+        if (value.schemaVersion !== (marker ? "itpay.device-generation.v1" : "itpay.device-session.v1"))
+            throw invalid("DEVICE_CACHE_CORRUPT");
+        if (typeof value.agentType !== "string")
+            throw invalid("DEVICE_CACHE_CORRUPT");
+        const cache = new DeviceSessionCache(directory, value);
+        if ((marker ? cache.generationPath : cache.cachePath) !== join(directory, file))
+            throw invalid("DEVICE_CACHE_CONTEXT_INVALID");
+        if (marker)
+            cache.generation(false);
+        types.add(value.agentType);
+    }
+    return [...types].sort();
+}

package/docs/agent/buyer/identity-and-sessions.json

@@ -20,13 +20,13 @@
     "The CLI reuses a valid cached device session.",
     "On one HTTP 401 with code agent_device_session_required, it invalidates only the current Backend and Agent Type session, renews it, and retries the exact request once.",
     "A second failure is returned to the Agent. The CLI does not loop, switch Agent Type, rotate the key, or create a replacement v2 device.",
-    "When a previously unseen Agent Type is registered under an existing Device, the CLI skips locally known Agent Instances that the Backend reports as revoked and uses the first remaining valid Instance. It never reactivates a revoked Instance or replaces the Device; if none is valid, registration stops.",
-    "When the Backend reports agent_device_not_found (HTTP 404) for a locally known registration — for example after the Backend registration database was rebuilt — the CLI drops only that Backend's registration and re-enrolls once with the same private key, re-attaching to the same device and quota lineage where the Backend still holds the key.",
+    "A new actual Agent Type proves possession of the original key to the selected Backend; the Backend resolves its original Device and idempotent Instance. Revoked Device, key or requested Instance is not replaced or reactivated.",
+    "An unknown Backend registration is re-attached once with the same key; only that Backend cache changes. The old identity file is read-only and other contexts remain intact.",
     "A revoked v2 registration requires explicit operator recovery; it is never silently replaced.",
-    "Re-enrolling a public key the Backend already holds re-attaches to the existing device and quota lineage after proof-of-possession; it never creates a duplicate device. An internal_error is a server failure: preserve the key and wait for service recovery. If enrollment returns agent_device_key_rotated or agent_device_key_conflict, stop automatic recovery. Only an explicit human/operator decision to abandon the old identity permits reset-key; old execution access does not migrate."
+    "Re-enrolling the same public key preserves the Backend Device and quota lineage after proof. internal_error is a server failure: preserve the key. Rotated/conflicting keys stop this round. This version does not support device reset-key; it returns device_key_reset_unavailable without changing identity."
   ],
   "local_state_recovery": [
-    "Device state uses an owner-only atomic file replacement and a lock that the CLI can inspect. On a stale lock, run the returned device repair-lock command; it only reclaims a proven stale owner.",
+    "The original key is retained; old identity is read-only. Each Backend/Agent Type/key fingerprint has an independent atomic session cache and generation marker. Normal authorization needs no legacy lock or process probe. Old lock files are not read, moved or deleted.",
     "Operation idempotency uses one immutable owner-only record per operation key. Different commands and Agent processes do not share a global operation-journal lock; legacy operations.json is read only.",
     "On device_state_unwritable, use the reported operation and errno to diagnose the failing stage without exposing local paths; keep the same Agent Type and CLI/Node launcher, restore Host-approved persistent access to ~/.itpay-v3, then retry the original command.",
     "Do not delete a live lock, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
@@ -40,17 +40,17 @@
     {
       "intent": "confirm the selected official Backend is available",
       "command": "itpay --agent-type <agent_type> readyz --json",
-      "success_signal": "Backend is available and onboarding returns to the Skill"
+      "success_signal": "Backend liveness only; next checks auth status with the same Backend and Agent Type"
     },
     {
       "intent": "recover after an operator-confirmed reset of the selected official Backend registration database",
       "command": "itpay --agent-type <agent_type> device recover --confirm-backend-reset --json",
-      "success_signal": "only the selected Backend registration is removed and the private key and other Backend registration remain"
+      "success_signal": "Only the selected Backend session caches are invalidated; key, old identity and other Backends remain"
     },
     {
-      "intent": "repair only a proven stale local device lock",
+      "intent": "compatibility explanation only; not a normal recovery action",
       "command": "itpay device repair-lock --json",
-      "success_signal": "the CLI reports whether the lock was stale and reclaimed; an active owner stays protected"
+      "success_signal": "device_legacy_lock_unmanaged; old files are untouched, not repaired"
     }
   ],
   "agent_rules": [
@@ -100,5 +100,5 @@
     "path_b": "A buyer who reaches checkout without a login completes identity inside the protected checkout page; never force a separate itpay auth login first.",
     "identity_binding": "Phone is recommended first, wallets next, email is a separate Other options choice. Extra identities are optional bindings. A phone conflict does not prove account ownership: independent target authentication and explicit human merge confirmation are required. Never use the same SMS proof twice, approve a merge for the user, or treat login/identity binding as payment consent. Service-specific contact requirements stay in the service."
   },
-  "key_reset_decision": "Only after explicit user/operator acceptance of abandoning the old identity, consult device reset-key help; this is not automatic error recovery, and old execution access does not migrate."
+  "key_reset_decision": "This version does not support device key reset, even after an explicit decision. Preserve identity and stop; do not delete the key or install an older CLI to perform a reset."
 }

package/docs/agent/buyer/rail-booking.json

@@ -141,7 +141,7 @@
     "booking_review_changed": "Read the current revision and compare material terms; confirm new terms only when changed.",
     "selection_stale": "Saved result stays readable, but follow the current owner action for new live inventory and quote evidence; do not assume reread refreshes the token.",
     "unknown_paid_outcome": "Read the same checkout/order before any mutation. Never repeat payment or create a new order on an unknown outcome.",
-    "lock": "Use the CLI returned device repair-lock recovery only for a lock proven stale; preserve active owners and identity.",
+    "lock": "Normal device authorization uses no legacy lock. Preserve identity and old lock files; follow the actual error stage, not a generic lock-repair command.",
     "empty": "Report verified scope, failures and missing evidence separately. Do not guess a new date or station as a generic repair. Explain checked scope first, then propose at most two evidence-backed directions. Ask consent before changing a locked endpoint; after consent copy the complete original input and change only the accepted side in a new query.",
     "ground_evidence_required": "If trains were found but a precise address deadline cannot be verified without ground or station-exit evidence, report the checked rail scope and missing fact. Ask for a precise location or verifiable connection fact; do not expand rail station pairs by default or call it no trains. Preserve the original place and compare its nearby candidates; only actual user consent may replace the destination with a station.",
     "dependency_unavailable": "Map faults are external failures, not empty location candidates. Preserve resolved endpoints and original conditions. For a retryable wait, respect dependency.retry_at and execute the returned same-execution run command; never restart or sleep inside the CLI. Daily quota, permission or IP failures need service maintenance, not a different address.",

package/docs/cli-reference/commands/device.md

@@ -1,70 +1,39 @@
-# `itpay device` / `itpay device recover`
+# `itpay device`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
+`itpay` is the single public CLI entry point; `$itpay` is its user-facing Skill invocation.
 
-## 范围
+## Stable identity and ordinary recovery
 
-`itpay device` 只显示该命令组的帮助并退出，不访问 Backend、不读取或修改身份。当前子命令是 `repair-lock`（检查并修复已退出进程留下的本地锁）、`recover`（运营确认 Backend 重置后删除本地登记）和 `reset-key`（服务端拒绝当前私钥登记时放弃本地密钥）。
+The original Ed25519 key stays at its existing location. Old `identity.json` v1/v2 is read-only compatibility data. Normal authorization does not acquire legacy locks, inspect processes, or create transition tickets/archives. Old lock files remain untouched.
 
-`itpay device repair-lock --json` 只检查本地锁，保留 Device identity；活跃锁返回 `device_lock_active`，过期锁修复后返回 `device_lock_recovered`，无锁返回 `device_lock_absent`。
+Each official Backend, actual Agent Type and current key fingerprint has its own atomic session cache. On a rejected session the CLI invalidates only that context, renews it, and retries the original request once. A second failure stops. Corrupt identity, missing original key, permission denial or unknown results never cause automatic key replacement. Do not delete identity, switch runtime/type or disable host protection.
 
-仅在运营明确确认当前 Backend 的 Device 登记数据库已重建或清空后，删除本地该 Backend 的 v2 registration：
+## `itpay device recover`
 
-```bash
+Only after an operator confirms the selected Backend registration database was reset:
+
+```sh
 itpay --agent-type <agent_type> device recover --confirm-backend-reset --json
 ```
 
-命令只作用于当前官方 Backend 的 Device registration，并保留本地 Ed25519 私钥、Cart 和业务资源。默认是 `https://app.itpay.ai`；显式测试可使用准确的 `ITPAY_BACKEND_URL=https://sandbox.itpay.ai`。该命令不访问 Backend、不自动创建新身份；返回的只读 `services list` 会保留同一 Backend，是重新登记入口。
+This invalidates the selected Backend's caches, preserves the key, old identity and other Backend contexts, and returns a same-Backend/type `auth status` command. It does not contact the Backend itself or authorize business. Missing type or confirmation fails before mutation. Do not use it for expiry, revocation, quota or an unconfirmed failure.
+
+Success status is `backend_cache_invalidated` or `backend_cache_absent`; `result.invalidated_agent_types` records the affected types. The next device check proves the original key to the selected Backend and reuses its authoritative Device/key/quota lineage. No token or private key appears in output.
 
-同一台电脑上的多个 Local Agent Type 共享本地 Device key，但各自使用独立 Agent
-Instance。CLI 只在原子更新 Device state 时使用短期本地锁；释放和 stale recovery
-通过 rename 完成，不依赖 Host 删除文件，因此 WorkBuddy 等 sandbox 的
-safe-delete/trash shim 不应阻断正常命令。该锁不在 Backend，不会让另一台电脑或
-另一个 Buyer 等待。遇到本地锁错误时不得删除 `~/.itpay-v3/device`、切换 Agent
-Type 或执行 `device recover`；锁忙用 `itpay device repair-lock --json` 检查，只回收已退出进程的锁。写盘权限错误按返回事实恢复宿主允许的持久写入权限后重试原命令，保持原身份。
+## `itpay device repair-lock`
+
+```sh
+itpay device repair-lock --json
+```
 
-缺少确认参数返回 `backend_reset_confirmation_required`。普通 session 失效由 CLI 自动续期；revoked、quota、权限或未知 Backend 故障不得使用本命令。所有 Agent Type 使用相同输入和输出合同。
+Compatibility explanation only: status `device_legacy_lock_unmanaged`, lock_status `unmanaged`, identity preserved. No legacy file is read, moved or deleted. This does not claim a lock was repaired. Ordinary authorization needs no lock cleanup.
 
 ## `itpay device reset-key`
 
-仅在确认当前密钥不可恢复，且服务端返回 `agent_device_key_rotated` / `agent_device_key_conflict` 时使用；`internal_error` 是服务端故障，不能据此重置身份。必须指定真实 Agent Type 并取得明确确认。这是本地操作，不访问 Backend：
+This version does not support automatic device key reset. The command name and existing type/confirmation guards remain recognized:
 
-```bash
+```sh
 itpay --agent-type <agent_type> device reset-key --confirm-key-reset --json
 ```
 
-命令删除本地 Ed25519 私钥并清空所有 Backend 的本地登记记录；下一次需要设备身份的命令会以全新密钥重新登记为新设备。服务端旧设备记录保留为孤儿，不会被删除或复用；原设备的额度谱系不迁移。正常续期与登记由 CLI 既有逻辑处理；仅在用户或运营明确决定放弃旧身份后才可执行换钥，旧执行访问不会迁移。锁超时使用 repair-lock，不重复登记或换钥。
-
-缺少确认参数返回 `key_reset_confirmation_required`；本地文件操作失败返回 `device_key_reset_failed`。本命令不得删除 Cart、operation journal 或 `~/.itpay-v3` 的其他内容。
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|---|---:|---|
-| 全局 `--agent-type <agent_type>` | 是 | 当前真实且稳定的 Agent Type；必须位于 `device` 前。 |
-| `--confirm-backend-reset` | 是 | 确认运营已明确判定所选 Backend 的登记数据库被重建或清空。 |
-| `--json` | 否 | 输出稳定 JSON 信封；否则输出同一事实的简洁文本。 |
-
-## 标准输出
-
-```json
-{
-  "status": "backend_registration_removed",
-  "result": {
-    "backend": "https://app.itpay.ai",
-    "removed_agent_types": ["codex-desktop"],
-    "private_key_preserved": true,
-    "other_backend_registrations_preserved": true
-  },
-  "instruction": "只读列出 Service Executions，以同一私钥和 Agent Type 重新登记当前 Backend；不要删除 ~/.itpay-v3 或切换运行时。",
-  "next": {
-    "command": "itpay --agent-type codex-desktop services list --limit 1 --json",
-    "reason": "用无业务写入的签名请求重新登记当前 Backend"
-  },
-  "recovery": []
-}
-```
-
-当前 Backend 已无本地登记时，`status` 为 `backend_registration_absent`、`removed_agent_types=[]`，其余合同不变。文本输出只包含 Backend、registration 状态、私钥保留和其他 Backend 保留四项，不输出私钥、公钥、Device ID、Agent Instance ID、session、token 或本地文件内容。
-
-缺少 Agent Type 返回 `agent_type_required`；缺少确认返回 `backend_reset_confirmation_required`。其他本地恢复失败返回 `device_recovery_failed`。所有失败都必须发生在删除 registration 前；本命令不得删除整把 Device identity、Cart、operation journal 或其他 Backend 登记。
+It returns nonzero `device_key_reset_unavailable`, next=null, recovery=[]; the original identity is unchanged. Do not delete a key manually, install an older version to reset it, or present this command as a recovery action. Restoring safe explicit key replacement requires a separately reviewed implementation.

package/docs/cli-reference/commands/install.md

@@ -8,7 +8,7 @@
 
 **上游：** 当前 npm CLI 或平台 bundle 已经可执行。
 
-**下游：** 使用真实 Agent Type 执行 `readyz`，随后读取完整 Skill 和 Catalog。
+**下游：** 先读取本包完整 Skill，使用真实 Agent Type 执行 `readyz`，再按返回的同 Backend/type 命令检查 `auth status`。authenticated 或成功 login_required 才证明设备访问可用；后者仍未登录，不自动发起授权或业务。
 
 ## 语法与参数
 

package/docs/cli-reference/commands/readyz.md

@@ -6,8 +6,8 @@
 
 检查当前官方 Backend 是否可用。默认使用生产环境 `https://app.itpay.ai`；仅测试时可通过 `ITPAY_BACKEND_URL=https://sandbox.itpay.ai` 选择官方沙箱环境。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
 
-**上游：** CLI 安装；Backend 只能是官方 `https://app.itpay.ai` 或 `https://sandbox.itpay.ai`，其他 override 在网络或本地状态写入前被拒绝。
-**下游：** 完整 `itpay` Skill；由 Agent 根据用户意图选择新服务、已购内容、订单或退款入口。
+**上游：** CLI 安装；Backend 只能是官方 `https://app.itpay.ai` 、`https://sandbox.itpay.ai` 或 `https://dev.itpay.ai`，其他 override 在网络或本地状态写入前被拒绝。
+**下游：** 实际宿主已声明时，执行同 Backend/type 的 `auth status`；未声明时先 `install` 选择实际宿主。首次准备先读本包 Skill，同版本不重复读取。
 
 ## 语法与参数
 
@@ -25,8 +25,8 @@ itpay readyz [--json]
 {
   "status": "ready",
   "result": { "backend": "available", "backend_url": "https://app.itpay.ai", "environment": "production" },
-  "instruction": "ItPay 可用。先完整读取内置 Skill，再根据用户意图选择新服务、已购内容、订单或退款入口；不要默认开始购买。",
-  "next": { "command": "itpay skill show itpay --json", "reason": "加载完整操作与安全规则" },
+  "instruction": "ItPay 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；不自动登录或开始业务。",
+  "next": { "command": "itpay install --json", "reason": "选择实际宿主，再检查设备访问；尚未读本包 Skill 时先完整读取" },
   "recovery": []
 }
 ```
@@ -37,8 +37,8 @@ itpay readyz [--json]
 {
   "status": "ready",
   "result": { "backend": "available", "backend_url": "https://sandbox.itpay.ai", "environment": "development" },
-  "instruction": "ItPay sandbox 可用。先完整读取内置 Skill，再根据用户意图选择新服务、已购内容、订单或退款入口；后续必须执行返回的完整命令并保持同一 sandbox Backend。",
-  "next": { "command": "ITPAY_BACKEND_URL=https://sandbox.itpay.ai itpay skill show itpay --json", "reason": "加载完整操作与安全规则" },
+  "instruction": "ItPay 开发环境 https://sandbox.itpay.ai 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；后续必须执行返回的完整命令并保持同一 Backend。",
+  "next": { "command": "ITPAY_BACKEND_URL=https://sandbox.itpay.ai itpay install --json", "reason": "选择实际宿主，再检查设备访问；尚未读本包 Skill 时先完整读取" },
   "recovery": []
 }
 ```
@@ -66,4 +66,4 @@ itpay readyz [--json]
 
 ## Agent Type / Host
 
-本命令不渲染 Host 内容。若已声明 Agent Type，`result.agent_type` 会确认该类型，且返回的 Skill 命令保留同一 `--agent-type`；未声明时 Skill 会先引导 `install`。
+本命令不渲染 Host 内容。若已声明 Agent Type，`result.agent_type` 会确认该类型，且返回的 `auth status` 命令保留同一 `--agent-type` 与 Backend；未声明时返回 `install`。只有 authenticated 或成功 login_required 才证明设备可用，后者不代表已登录。权限拒绝或未知状态停止准备，不宣称 ready。

package/node_modules/@hono/node-server/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 - present, Yusuke Wada and Hono contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.