@itpay/cli 2.1.40 → 2.1.44

package/dist/src/main.js

@@ -144,18 +144,15 @@ function reportCLIError(error, contract) {
             reason: "读取 ItPay 身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
         },
     ] : [];
-    const stateRecovery = stateError ? [{
-            command: "itpay skill show itpay --json",
-            reason: "读取 Device 状态边界；修复当前 Host 的持久写权限后重试原命令",
-        }] : [];
+    const stateRecovery = [];
     const lockRecovery = lockError ? [{
             command: "itpay device repair-lock --json",
             reason: "检查锁持有者；只回收已退出进程留下的锁，不改变设备身份",
         }] : [];
     const authorizationInstruction = stateError
-        ? `当前运行环境无法写入 owner-only Device 状态；受阻路径 ${stateError.blockedPath ?? "~/.itpay-v3"}，操作 ${stateError.operation}（${stateError.causeCode}）。保持同一 Node、CLI 和 Agent Type，修复该路径持久写权限后重试原命令；不要手工创建 lock、删除 identity、随意更换 HOME 或换运行时。`
+        ? `本地设备状态操作未完成：${stateError.operation}（${stateError.causeCode}，来源 ${stateError.source}）。保持原身份和已有授权；由环境负责人核对该操作、锁持有者和宿主返回。权限错误才检查读写权限；未知操作结果先核对现场，不盲目重试，不删除身份或绕过宿主保护。`
         : lockError
-            ? "另一个进程仍在更新本地身份。执行 recovery 检查；若持有者仍活跃，等待后继续原任务，不要删除锁或重建身份。"
+            ? "本地身份锁占用或安全转换未完成。执行 recovery 核对；活跃持有者需等待，遗留转换需环境负责人检查。不能仅凭等待时间删锁或重建身份。"
             : error instanceof HttpError && error.code === "agent_device_session_required"
                 ? "CLI 已自动续期并重试同一请求一次，仍被拒绝；停止重试，不要切换 Agent Type 或旋转身份。"
                 : deviceError?.code === "agent_device_revoked"
@@ -174,7 +171,7 @@ function reportCLIError(error, contract) {
                 code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : transportError?.code ?? stateError?.code ?? lockError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
-            ...(commandError?.result ? { result: commandError.result } : incompatible && error instanceof HttpError ? {
+            ...(stateError ? { result: { failure_stage: "local_device_state", operation: stateError.operation, cause_code: stateError.causeCode, source: stateError.source } } : commandError?.result ? { result: commandError.result } : incompatible && error instanceof HttpError ? {
                 result: {
                     current_cli_version: CLI_VERSION,
                     current_api_contract_revision: API_CONTRACT_REVISION,
@@ -318,6 +315,8 @@ for (const action of ["login", "status"]) {
                 recovery: (result.recovery ?? []),
             };
             writeCommandEnvelope(envelope, { jsonOutput: Boolean(options.json) });
+            if (envelope.status === "auth_status_unknown")
+                process.exitCode = 1;
         }
         catch (error) {
             reportCLIError(error, { jsonOutput: Boolean(options.json), code: "account_login_failed", initialization: true, instruction: "本轮授权检查未完成；保留设备及已有授权状态，按明确错误原因恢复。不要自动发起新的登录。" });
@@ -341,7 +340,7 @@ deviceCmd
         writeCommandEnvelope({
             status: status === "recovered" ? "device_lock_recovered" : status === "active" ? "device_lock_active" : "device_lock_absent",
             result: { lock_status: status, device_identity_preserved: true },
-            instruction: status === "active" ? "本地身份正由存活进程更新；稍后继续原任务。" : "本地锁无需进一步处理；继续原任务。",
+            instruction: status === "active" ? "本地锁占用或安全转换未完成；保留原身份，核对持有者及宿主现场后继续原任务。" : "本地锁无需进一步处理；继续原任务。",
             next: null,
             recovery: [],
         }, { jsonOutput: Boolean(options.json), plainResult: [`lock: ${status}`, "device_identity: preserved"] });

package/dist/src/services/rail/adapter.js

@@ -11,7 +11,6 @@ import { railCheckoutItinerary } from "./checkout.js";
 import { renderRailResultPage } from "./page.js";
 import { readSavedResult } from "./reading.js";
 export const railAdapter = {
-    aftercare: { order: railAftercareOrder, directory: railAftercareList, present: railAftercareEnvelope, create: railAftercareCreate, respond: railAftercareRespond },
     entryInstruction: RAIL_ENDPOINT_BRIEF + "按 result.guidance 逐项填写输入（when_to_use 说明本服务适用场景、input_fields 是必填契约、input_example 是待填示意，必须替换用户真实值），然后继续同一服务执行。不要臆造字段名。",
     supported: true, inputTemplate: railInputTemplate, inputInstruction: railInputRecoveryInstruction,
     guidance: railServiceGuidance, requiresGuidance: id => id === "itpay-rail-smart",
@@ -25,3 +24,13 @@ export const railAdapter = {
     renderPage: (...args) => { renderRailResultPage(...args); return true; },
     checkout: async (backend, model, id, token) => railCheckoutItinerary(model, await backend.getCheckoutPresentation(id, token)),
 };
+const bookingAdapter = {
+    ...railAdapter,
+    aftercare: { order: railAftercareOrder, directory: railAftercareList, present: railAftercareEnvelope, create: railAftercareCreate, respond: railAftercareRespond },
+};
+export function railAdapterFor(identity) {
+    const booking = identity.public_binding
+        ? identity.public_binding.operation_id === "prepare_purchase"
+        : identity.service_id === "itpay-rail-booking";
+    return booking ? bookingAdapter : railAdapter;
+}

package/dist/src/services/registry.js

@@ -1,4 +1,4 @@
-import { railAdapter } from "./rail/adapter.js";
+import { railAdapterFor } from "./rail/adapter.js";
 import { schemaAdapter, unsupportedAdapter } from "./schema.js";
 // Published identities are frozen compatibility contracts. Fields named
 // endpoints/review/search, titles and ID prefixes never choose a business adapter.
@@ -27,5 +27,5 @@ export function serviceClientFeatures() {
 }
 export function serviceAdapter(execution) {
     const key = serviceAdapterKey(execution);
-    return key === "rail.v1" ? railAdapter : key === "schema.v1" ? schemaAdapter : unsupportedAdapter;
+    return key === "rail.v1" ? railAdapterFor(execution) : key === "schema.v1" ? schemaAdapter : unsupportedAdapter;
 }

package/dist/src/state/account_auth.js

@@ -78,7 +78,7 @@ class AuthRequestError extends Error {
 }
 // AUTH03: transport/read uncertainty never maps to "denied" or a new session —
 // the stored session stays on disk and the caller retries the same poll.
-function authStatusUnknown(sessionID, error) {
+function authStatusUnknown(sessionID, error, failureStage = "authorization_status_read") {
     // These errors have definite compatibility/identity/state facts. Let the
     // command boundary report them rather than turning them into polling.
     if ((error instanceof HttpError && error.status < 500)
@@ -86,16 +86,23 @@ function authStatusUnknown(sessionID, error) {
         || error instanceof DeviceAuthorizationError || error instanceof DeviceStateError
         || error instanceof DeviceLockBusyError)
         throw error;
+    const hostFailure = error && typeof error === "object" && "code" in error
+        && (error.code === "CODEBUDDY_BROKER_DENY" || error.code === "CODEBUDDY_BROKER_OUTCOME_UNKNOWN");
     const failure = error instanceof HttpTransportError
-        ? { category: error.code, attempts: error.attempts }
-        : { category: 'authorization_status_unavailable' };
+        ? { category: error.code, attempts: error.attempts, source: "network_transport" }
+        : error instanceof HttpError || error instanceof AuthRequestError
+            ? { category: "http_server_error", http_status: error instanceof HttpError ? error.status : error.httpStatus, source: "http_response" }
+            : hostFailure ? { category: "host_operation_unavailable", source: "host_broker" }
+                : { category: "authorization_status_unavailable", source: "unclassified" };
     return {
         status: 'auth_status_unknown',
-        result: { ...failure, ...(sessionID ? { dashboard_auth_session_id: sessionID } : {}) },
-        instruction: sessionID
-            ? '读取官方授权状态失败；原授权请求已保留。稍后重读同一状态，不要新建授权、不要清除本地登记。'
-            : '本轮账号绑定检查未完成，设备与绑定状态尚未确认；没有保存的授权请求。结束本轮，网络或服务恢复后可重新检查，不发起登录。',
-        next: sessionID ? { command: 'itpay auth status --json', reason: '稍后重读同一授权状态', poll_after_ms: 5000 } : null,
+        result: { ...failure, failure_stage: failureStage, ...(sessionID ? { dashboard_auth_session_id: sessionID } : {}) },
+        instruction: hostFailure || failure.source === 'unclassified'
+            ? '本轮授权检查未完成，底层原因尚未确定；保留设备和已有授权，请维护方核对当前失败阶段及宿主结果，不自动登录、换身份或盲目重复修改。'
+            : sessionID
+                ? '读取官方授权状态失败；原授权请求已保留。稍后重读同一状态，不要新建授权、不要清除本地登记。'
+                : '本轮账号绑定检查未完成，设备与绑定状态尚未确认；没有保存的授权请求。结束本轮，网络或服务恢复后可重新检查，不发起登录。',
+        next: sessionID && !hostFailure && failure.source !== 'unclassified' ? { command: 'itpay auth status --json', reason: '稍后重读同一授权状态', poll_after_ms: 5000 } : null,
         recovery: [],
     };
 }
@@ -149,7 +156,7 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
                 throw error;
             // AUTH03: even the binding-status probe can hit transport failure; the
             // truthful state is "unknown", never an implicit unbound or a fresh login.
-            return authStatusUnknown(read(baseURL, env, purpose)?.sessionID, error);
+            return authStatusUnknown(read(baseURL, env, purpose)?.sessionID, error, "account_binding_probe");
         }
     }
     async function request(path, init = {}) {

package/dist/src/state/config.js

@@ -15,8 +15,8 @@ import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
 export const DEV_BASE_URL = "https://dev.itpay.ai";
 export const SANDBOX_BASE_URL = "https://sandbox.itpay.ai";
-export const CLI_VERSION = "2.1.40";
-export const API_CONTRACT_REVISION = "sha256:700d9834de969f16d0fc58cbbdbaa092f969f497e30e4ec291c790cea3e7f73a";
+export const CLI_VERSION = "2.1.44";
+export const API_CONTRACT_REVISION = "sha256:c1e1f459c1d3844f6eeae21535b532abb2e48c3e320173c4faccd62992890dcd";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";

package/dist/src/state/device_authority.js

@@ -1,7 +1,7 @@
 import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign, } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, lstatSync, linkSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, resolve } from "node:path";
-const PROTECTED_PATHS = ["/v1/agent-device-account-bindings", "/v1/carts", "/v1/service-executions", "/v1/agent-instances", "/v1/orders", "/v1/refunds", "/v1/me", "/v1/vault", "/v1/rail/phone-links"];
+const PROTECTED_PATHS = ["/v1/agent-device-account-bindings", "/v1/carts", "/v1/service-executions", "/v1/agent-instances", "/v1/orders", "/v1/refunds", "/v1/me", "/v1/vault", "/v1/rail/phone-links", "/v1/rail-aftercare"];
 export class DeviceAuthority {
     baseURL;
     backendKey;
@@ -101,7 +101,7 @@ export class DeviceAuthority {
                 }
                 catch (error) {
                     if (error.code !== "ENOENT") {
-                        throw asDeviceStateError(error, "remove_private_key") ?? error;
+                        throw asDeviceStateError(error, "remove_private_key");
                     }
                 }
             }
@@ -272,10 +272,7 @@ export class DeviceAuthority {
             return undefined;
         }
         catch (error) {
-            const stateError = asDeviceStateError(error, "read_state");
-            if (stateError)
-                throw stateError;
-            return undefined;
+            throw asDeviceStateError(error, "read_state");
         }
     }
     readPrivateKey() {
@@ -285,10 +282,7 @@ export class DeviceAuthority {
             return createPrivateKey(readFileSync(this.privateKeyPath, "utf8"));
         }
         catch (error) {
-            const stateError = asDeviceStateError(error, "read_private_key");
-            if (stateError)
-                throw stateError;
-            return undefined;
+            throw asDeviceStateError(error, "read_private_key");
         }
     }
     writeState(state) { atomicOwnerOnlyWrite(this.statePath, JSON.stringify(state, null, 2), "write_state"); }
@@ -309,19 +303,22 @@ export class DeviceStateError extends Error {
     operation;
     causeCode;
     blockedPath;
-    code = "device_state_unwritable";
+    code = "device_state_unavailable";
+    source;
     constructor(operation, causeCode, blockedPath) {
         super(`ItPay device state operation failed: ${operation} (${causeCode})`);
         this.operation = operation;
         this.causeCode = causeCode;
         this.blockedPath = blockedPath;
         this.name = "DeviceStateError";
+        this.source = causeCode === "UNCLASSIFIED_LOCAL_FAILURE" ? "unclassified_local_operation" : causeCode.startsWith("CODEBUDDY_BROKER_") ? "host_broker"
+            : ["LEGACY_LOCK_OWNER_UNKNOWN", "SYMLINK_LOCK", "LOCK_SOURCE_CHANGED", "LOCK_TRANSITION_BUSY", "LOCK_OWNER_PROBE_UNAVAILABLE"].includes(causeCode) ? "client_state_validation" : "native_filesystem";
     }
 }
 export class DeviceLockBusyError extends Error {
     code = "device_lock_busy";
     constructor() {
-        super("ItPay device identity is being updated by another process");
+        super("ItPay device lock is occupied or its transition cannot be safely completed");
         this.name = "DeviceLockBusyError";
     }
 }
@@ -359,7 +356,7 @@ function atomicOwnerOnlyWrite(path, value, operation) {
             unlinkSync(temporary);
         }
         catch { /* best-effort cleanup */ }
-        throw asDeviceStatePathError(error, operation) ?? error;
+        throw asDeviceStatePathError(error, operation);
     }
 }
 async function withFileLock(path, run) {
@@ -367,46 +364,71 @@ async function withFileLock(path, run) {
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     }
     catch (error) {
-        throw asDeviceStatePathError(error, "prepare_lock") ?? error;
+        throw asDeviceStatePathError(error, "prepare_lock");
     }
     const ownerToken = `${process.pid}:${randomUUID()}`;
     let acquired = false;
     for (let attempt = 0; attempt < 800; attempt += 1) {
         try {
-            writeFileSync(path, ownerToken, { encoding: "utf8", flag: "wx", mode: 0o600 });
-            chmodSync(path, 0o600);
+            if (!lockTransition(path, () => {
+                writeFileSync(path, ownerToken, { encoding: "utf8", flag: "wx", mode: 0o600 });
+                chmodSync(path, 0o600);
+            })) {
+                await new Promise((resolve) => setTimeout(resolve, 25));
+                continue;
+            }
             acquired = true;
             break;
         }
         catch (error) {
             const code = error.code;
             if (code !== "EEXIST")
-                throw asDeviceStateError(error, "acquire_lock") ?? error;
+                throw asDeviceStateError(error, "acquire_lock");
             inspectAndRecoverLock(path);
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
     }
     if (!acquired)
         throw new DeviceLockBusyError();
+    let operationFailed = false;
     try {
         return await run();
     }
+    catch (error) {
+        operationFailed = true;
+        throw error;
+    }
     finally {
-        releaseLock(path, ownerToken);
+        try {
+            await releaseLock(path, ownerToken);
+        }
+        catch (error) {
+            if (!operationFailed)
+                throw error;
+        }
     }
 }
 function inspectAndRecoverLock(path) {
+    let result = "active";
+    lockTransition(path, () => { result = inspectLockOwner(path); });
+    return result;
+}
+function inspectLockOwner(path) {
     let token;
     let age;
+    let inspected;
     try {
-        const lockStat = statSync(path);
+        const lockStat = lstatSync(path);
+        if (lockStat.isSymbolicLink())
+            throw new DeviceStateError("inspect_lock", "SYMLINK_LOCK");
+        inspected = lockStat;
         age = Date.now() - lockStat.mtimeMs;
         token = lockStat.isDirectory() ? "" : readFileSync(path, "utf8");
     }
     catch (error) {
         if (error.code === "ENOENT")
             return "absent";
-        throw asDeviceStateError(error, "inspect_lock") ?? error;
+        throw asDeviceStateError(error, "inspect_lock");
     }
     const ownerPID = /^(\d+):[0-9a-f-]+$/.exec(token)?.[1];
     if (ownerPID) {
@@ -419,8 +441,11 @@ function inspectAndRecoverLock(path) {
                 return "active";
         }
     }
-    else if (age <= 30_000) {
-        return "active";
+    else {
+        if (age <= 30_000)
+            return "active";
+        // Legacy ownerless locks cannot prove that an old caller has exited.
+        throw new DeviceStateError("inspect_lock", "LEGACY_LOCK_OWNER_UNKNOWN");
     }
     // Recheck the exact owner before moving the lock; another process may have renewed it.
     try {
@@ -430,45 +455,250 @@ function inspectAndRecoverLock(path) {
     catch (error) {
         if (error.code === "ENOENT")
             return "absent";
-        throw asDeviceStateError(error, "inspect_lock") ?? error;
+        throw asDeviceStateError(error, "inspect_lock");
     }
-    moveLockAside(path, "stale", "remove_stale_lock");
+    moveLockAside(path, "stale", "remove_stale_lock", inspected);
     return "recovered";
 }
-function releaseLock(path, ownerToken) {
+async function releaseLock(path, ownerToken) {
+    // Another caller may be inspecting our live owner under the same short
+    // transition. Wait for that critical section, without reclaiming its guard.
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        if (lockTransition(path, () => releaseOwnedLock(path, ownerToken)))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    throw new DeviceStateError("release_lock", "LOCK_TRANSITION_BUSY");
+}
+function releaseOwnedLock(path, ownerToken) {
     try {
+        const inspected = lstatSync(path);
+        if (!inspected.isFile())
+            throw new DeviceStateError("release_lock", "LOCK_SOURCE_CHANGED");
         if (readFileSync(path, "utf8") !== ownerToken)
             return;
-        moveLockAside(path, "released", "release_lock");
+        moveLockAside(path, "released", "release_lock", inspected);
     }
     catch (error) {
         if (error.code !== "ENOENT")
-            throw asDeviceStateError(error, "release_lock") ?? error;
+            throw asDeviceStateError(error, "release_lock");
     }
 }
-function moveLockAside(path, suffix, operation) {
+// Per-process tickets publish ownership in the directory name before any write.
+// The pool itself is not a lock. An interrupted choosing/ready ticket is ignored
+// only after its PID is proven dead; no caller removes another caller's ticket.
+// New arrivals choose a larger ticket, and simultaneous choices use name order.
+function lockTransition(path, run) {
+    const legacy = `${path}.transition`;
+    const pool = `${path}.transition-owners`;
+    mkdirSync(pool, { recursive: true, mode: 0o700 });
+    if (lstatSync(pool).isSymbolicLink())
+        throw new DeviceStateError("inspect_lock", "SYMLINK_LOCK");
+    const incarnation = processIncarnation(process.pid);
+    if (!incarnation)
+        throw new DeviceStateError("prepare_lock", "LOCK_OWNER_PROBE_UNAVAILABLE");
+    // mkdir publishes the choosing owner and its incarnation in one atomic step.
+    const name = `${process.pid}-${sha256(incarnation).slice(7)}-${randomUUID()}`;
+    const own = resolve(pool, name);
+    mkdirSync(own, { mode: 0o700 });
+    let failed = false;
+    let linked = false;
+    const token = JSON.stringify({ pid: process.pid, incarnation, token: randomUUID() });
     try {
-        renameSync(path, `${path}.${suffix}`);
+        let ticket = 1;
+        for (const other of readdirSync(pool)) {
+            if (other === name || other === "archives")
+                continue;
+            const value = transitionTicket(pool, other);
+            if (value !== undefined)
+                ticket = Math.max(ticket, (value ?? 0) + 1);
+        }
+        if (!Number.isSafeInteger(ticket))
+            throw new DeviceStateError("inspect_lock", "LOCK_TRANSITION_BUSY");
+        writeFileSync(resolve(own, "ticket"), JSON.stringify({ sequence: ticket, incarnation }), { flag: "wx", mode: 0o600 });
+        for (const other of readdirSync(pool)) {
+            if (other === name || other === "archives")
+                continue;
+            const value = transitionTicket(pool, other);
+            if (value === null || (value !== undefined && (value < ticket || (value === ticket && other < name))))
+                return false;
+        }
+        // All new binaries hold the ticket mutex during stale recovery. Old binaries
+        // see EEXIST on this same path, so cannot race acquisition with recovery.
+        if (existsSync(legacy)) {
+            const stat = lstatSync(legacy);
+            if (!stat.isFile())
+                return false; // Unknown old directory owner stays protected.
+            const text = readFileSync(legacy, "utf8");
+            const old = /^(\d+):[0-9a-f-]+$/.exec(text);
+            let ownerPID;
+            let birth;
+            if (old)
+                ownerPID = Number(old[1]);
+            else {
+                let value;
+                try {
+                    value = JSON.parse(text);
+                }
+                catch {
+                    return false;
+                }
+                if (!value || typeof value !== "object" || !("pid" in value) || typeof value.pid !== "number" || !("incarnation" in value) || typeof value.incarnation !== "string")
+                    return false;
+                ownerPID = value.pid;
+                birth = value.incarnation;
+            }
+            if (!Number.isSafeInteger(ownerPID) || ownerPID <= 0)
+                return false;
+            try {
+                process.kill(ownerPID, 0);
+                const current = birth && processIncarnation(ownerPID);
+                if (!current || current === birth)
+                    return false;
+            }
+            catch (error) {
+                if (error.code !== "ESRCH")
+                    return false;
+            }
+            moveLockAside(legacy, "stale", "remove_stale_lock", stat);
+        }
+        const owner = resolve(own, "owner");
+        writeFileSync(owner, token, { flag: "wx", mode: 0o600 });
+        // Hard-link a fully written owner: no empty/unowned publication crash gap.
+        try {
+            linkSync(owner, legacy);
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+        linked = true;
+        run();
+        return true;
     }
     catch (error) {
-        const code = error.code;
-        if (code === "ENOENT")
-            return;
-        if (code === "EEXIST" || code === "ENOTEMPTY") {
-            renameSync(path, `${path}.${suffix}.${randomUUID()}`);
-            return;
+        failed = true;
+        throw error;
+    }
+    finally {
+        try {
+            if (linked) {
+                if (readFileSync(legacy, "utf8") !== token)
+                    throw new DeviceStateError("release_lock", "LOCK_SOURCE_CHANGED");
+                renameSync(legacy, resolve(own, "transition-released"));
+            }
+            const archive = resolve(pool, "archives");
+            mkdirSync(archive, { recursive: true, mode: 0o700 });
+            if (lstatSync(archive).isSymbolicLink())
+                throw new DeviceStateError("release_lock", "SYMLINK_LOCK");
+            const destination = resolve(archive, randomUUID());
+            mkdirSync(destination, { mode: 0o700 });
+            renameSync(own, resolve(destination, "entry"));
+        }
+        catch (error) {
+            if (!failed)
+                throw asDeviceStateError(error, "release_lock");
+        }
+    }
+}
+// undefined = absent/dead, null = a live process still choosing its ticket.
+function transitionTicket(pool, name) {
+    const owner = /^(\d+)-(?:([0-9a-f]{64})-)?[0-9a-f-]+$/.exec(name);
+    if (!owner || Number(owner[1]) <= 0)
+        throw new DeviceStateError("inspect_lock", "LOCK_SOURCE_CHANGED");
+    try {
+        process.kill(Number(owner[1]), 0);
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return undefined;
+        return null;
+    }
+    if (owner[2]) {
+        const birth = processIncarnation(Number(owner[1]));
+        if (!birth)
+            return null;
+        if (sha256(birth).slice(7) !== owner[2])
+            return undefined;
+    }
+    try {
+        const entry = resolve(pool, name);
+        if (!lstatSync(entry).isDirectory())
+            throw new DeviceStateError("inspect_lock", "SYMLINK_LOCK");
+        const file = resolve(entry, "ticket");
+        if (lstatSync(file).isSymbolicLink())
+            throw new DeviceStateError("inspect_lock", "SYMLINK_LOCK");
+        let value;
+        try {
+            value = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            return null;
         }
-        throw asDeviceStateError(error, operation) ?? error;
+        if (!value || typeof value !== "object" || !("sequence" in value) || typeof value.sequence !== "number" || !("incarnation" in value) || typeof value.incarnation !== "string")
+            return null;
+        const birth = processIncarnation(Number(owner[1]));
+        if (!birth)
+            return null;
+        if (birth !== value.incarnation)
+            return undefined; // PID belongs to a different process.
+        return Number.isSafeInteger(value.sequence) && value.sequence > 0 ? value.sequence : null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return existsSync(resolve(pool, name)) ? null : undefined;
+        }
+        throw asDeviceStateError(error, "inspect_lock");
+    }
+}
+// Built-in OS process metadata distinguishes reused PIDs without an age timeout.
+// If probing is unavailable, ownership stays conservative rather than stolen.
+function processIncarnation(pid) {
+    try {
+        if (process.platform === "linux") {
+            const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+            const started = stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19];
+            return started ? `${readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()}:${started}` : undefined;
+        }
+        const output = process.platform === "win32"
+            ? execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `(Get-Process -Id ${pid}).StartTime.ToUniversalTime().ToString('o')`], { encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"] })
+            : execFileSync("ps", ["-p", String(pid), "-o", "lstart="], { encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"], env: { ...process.env, LC_ALL: "C", TZ: "UTC" } });
+        return output.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function moveLockAside(path, suffix, operation, source) {
+    try {
+        if (source.isSymbolicLink())
+            throw new DeviceStateError(operation, "SYMLINK_LOCK");
+        // Reserve a private, unique destination; never rename over shared archives.
+        const archive = `${path}.${suffix}.${randomUUID()}`;
+        mkdirSync(archive, { mode: 0o700 });
+        const current = lstatSync(path);
+        if (source.dev !== current.dev || source.ino !== current.ino || source.mtimeMs !== current.mtimeMs || source.size !== current.size) {
+            throw new DeviceStateError(operation, "LOCK_SOURCE_CHANGED");
+        }
+        renameSync(path, `${archive}/lock`);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw asDeviceStateError(error, operation);
     }
 }
 function asDeviceStateError(error, operation) {
-    const code = error.code;
-    return code === "EACCES" || code === "EPERM" || code === "EROFS" || code === "ENOTDIR" || code === "EISDIR"
-        ? new DeviceStateError(operation, code, error.path)
-        : undefined;
+    if (error instanceof DeviceStateError)
+        return error;
+    const code = error?.code;
+    const known = ["EACCES", "EPERM", "EROFS", "ENOTDIR", "EISDIR", "EEXIST", "ENOENT", "ENOTEMPTY", "ENOSPC", "EMFILE", "EIO", "CODEBUDDY_BROKER_DENY", "CODEBUDDY_BROKER_OUTCOME_UNKNOWN"];
+    return new DeviceStateError(operation, typeof code === "string" && known.includes(code) ? code : "UNCLASSIFIED_LOCAL_FAILURE");
 }
 function asDeviceStatePathError(error, operation) {
     const code = error.code;
     return code === "EEXIST" ? new DeviceStateError(operation, code, error.path) : asDeviceStateError(error, operation);
 }
 import { stateDir } from "./config.js";
+import { execFileSync } from "node:child_process";

package/docs/agent/buyer/install-and-setup.json

@@ -28,18 +28,19 @@
     {
       "intent": "verify the selected official Backend",
       "command": "<execute the exact next.command returned by install>",
-      "success_signal": "status is ready and next points to the packaged Skill with the same Agent Type and Backend"
+      "success_signal": "ready proves Backend liveness only; retain the actual Agent Type and Backend, then verify device access"
     },
     {
-      "intent": "load the complete packaged operating contract",
-      "command": "<execute the exact next.command returned by readyz>",
-      "success_signal": "status is shown and next is null so the Agent can route the human's natural-language intent"
+      "intent": "verify device access after Backend liveness",
+      "command": "itpay auth status --json",
+      "success_signal": "authenticated or successful login_required proves device access; pending/unknown is not ready"
     }
   ],
   "agent_rules": [
     "For first setup, read the complete Skill from this installed package before network checks. Select the actual Agent Type once through install and retain the same launcher and Backend. Do not reread the same version Skill, repeat initialization for ordinary tasks, or start login or business to prove setup.",
-    "After setup, tell the human only that ItPay is ready; never ask them to run setup commands or explain technical setup steps.",
-    "Use the CLI distribution already provided by the current npm package, Skill, or plugin; update only through that distribution's own instructions.",
+    "Run installation separately and preserve full output and its exit code. Nonzero stops preparation even if an older CLI runs. Same-version reuse requires verified executable, registry channel target, contract and official source; do not force or bypass host protection.",
+    "Report ItPay ready only after Backend and device checks succeed; otherwise preparation is incomplete. Account login is not required for setup.",
+    "The current public setup link selects the channel and matching contract: latest/app for production, next/dev for beta. Do not let an old bundle or memory override this choice.",
     "Production defaults to https://app.itpay.ai. Testing may set ITPAY_BACKEND_URL to the exact official URL the configured official test Backend only when explicitly requested; follow the CLI allowlist.",
     "If Backend compatibility cannot be verified, stop this round. minimum_cli_version is a protocol floor, not a verified matching artifact. Ask the maintainer for the matching distribution; do not guess a version or downgrade.",
     "Only install a replacement when its exact artifact and Backend contract have been verified; then reread that package Skill. Never change Agent Type or Device identity to recover compatibility.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.1.40",
+  "version": "2.1.44",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {
@@ -77,5 +77,5 @@
     "type": "git",
     "url": "git+https://github.com/itpay-ai/cli.git"
   },
-  "gitHead": "c83c252d8799ae75f036c81738addd44026f191d"
+  "gitHead": "e857df88cab7549f3ee011fc4e562ef2d40f8274"
 }

package/skills/itpay/SKILL.md

@@ -14,6 +14,8 @@ human the useful result or action, not the internal steps.
 
 ## Installation readiness
 
+The current setup link chooses the channel: production is latest/app; beta is next/dev. Keep this choice even if old memory or a bundled CLI suggests another version. Run any installation separately, read its full output and preserve its exit code; a failed installation ends preparation even when an old CLI still runs. Reuse requires verified executable, current channel version, contract and official package source. Do not force installation or bypass host protection.
+
 Read this installed package Skill before network checks. Select the actual Agent Type from `itpay install --json` and retain the same executable and Backend. readyz proves liveness only; after success, `itpay auth status --json` checks device access and binding. A successful authenticated or login_required response proves the device request worked; login_required does not require login during setup. Preserve any existing authorization. Unknown, missing-command, compatibility or exhausted network checks end this round without guessing commands/versions or reporting ready. minimum_cli_version is a protocol floor, not a verified artifact recommendation. Do not use services, orders or paid operations to prove installation. Already read same-version Skill needs no repeat.
 
 ## Choose one entry