@itpay/cli 2.0.5 → 2.0.7

package/dist/src/state/device_authority.js

@@ -1,10 +1,11 @@
-import { createHash, createPrivateKey, generateKeyPairSync, randomUUID, sign, } from "node:crypto";
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign, } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 const PROTECTED_PATHS = ["/v1/carts", "/v1/service-executions", "/v1/agent-instances", "/v1/orders", "/v1/refunds"];
 export class DeviceAuthority {
     baseURL;
+    backendKey;
     requestedAgentType;
     compatibilityHeaders;
     statePath;
@@ -13,6 +14,7 @@ export class DeviceAuthority {
     pending;
     constructor(options) {
         this.baseURL = options.baseURL.replace(/\/$/, "");
+        this.backendKey = normalizeBackendKey(options.baseURL);
         this.requestedAgentType = options.requestedAgentType;
         this.compatibilityHeaders = options.compatibilityHeaders;
         const root = resolve(homedir(), ".itpay-v3", "device");
@@ -47,54 +49,93 @@ export class DeviceAuthority {
         }
         return this.pending;
     }
+    async recoverAuthorization() {
+        await withFileLock(`${this.statePath}.lock`, async () => {
+            const state = this.readState();
+            if (!state || !this.requestedAgentType)
+                return;
+            const registration = state.registrations[this.backendKey];
+            if (!registration)
+                return;
+            delete registration.sessions[this.requestedAgentType];
+            this.writeState(state);
+        });
+    }
+    async recoverBackendReset() {
+        return withFileLock(`${this.statePath}.lock`, async () => {
+            const state = this.readState();
+            const registration = state?.registrations[this.backendKey];
+            if (!state || !registration)
+                return { removed: false, agentTypes: [] };
+            const agentTypes = Object.keys(registration.agentInstances).sort();
+            delete state.registrations[this.backendKey];
+            this.writeState(state);
+            return { removed: true, agentTypes };
+        });
+    }
     async prepareAuthorization() {
-        let state = this.readState();
-        const agentType = this.requestedAgentType ?? firstAgentType(state);
+        let state = this.readState() ?? emptyDeviceState();
+        const agentType = this.requestedAgentType;
         if (!agentType) {
             throw new Error("agent type is required for ItPay commerce; pass --agent-type <type> or set ITPAY_AGENT_TYPE");
         }
         let privateKey = this.readPrivateKey();
-        if (!state || !privateKey) {
-            const enrolled = await this.enroll(agentType);
-            state = enrolled.state;
-            privateKey = enrolled.privateKey;
+        if (!privateKey) {
+            const pair = generateKeyPairSync("ed25519");
+            privateKey = pair.privateKey;
+            this.writePrivateKey(pair.privateKey.export({ format: "pem", type: "pkcs8" }).toString());
+            state = emptyDeviceState();
         }
-        if (!state.agentInstances[agentType]) {
-            const existingType = firstAgentType(state);
+        let registration = state.registrations[this.backendKey];
+        if (!registration && state.legacyRegistration) {
+            try {
+                await this.ensureRegistrationAgentType(state.legacyRegistration, agentType, privateKey, true);
+                registration = state.legacyRegistration;
+                delete state.legacyRegistration;
+            }
+            catch (error) {
+                if (!canMovePastLegacyRegistration(error))
+                    throw error;
+            }
+        }
+        if (!registration) {
+            registration = await this.enroll(agentType, privateKey);
+        }
+        state.registrations[this.backendKey] = registration;
+        const session = await this.ensureRegistrationAgentType(registration, agentType, privateKey, false);
+        this.writeState(state);
+        return { state: registration, agentType, session, privateKey };
+    }
+    async ensureRegistrationAgentType(registration, agentType, privateKey, forceSession) {
+        if (!registration.agentInstances[agentType]) {
+            const existingType = firstAgentType(registration);
             if (!existingType)
                 throw new Error("device has no registered agent instance");
-            const existingSession = await this.ensureSession(state, existingType, privateKey);
-            const registered = await this.signedJSON("/v1/agent-instances", { agent_type: agentType }, state, existingType, existingSession, privateKey);
-            state.agentInstances[agentType] = registered.agent_instance_id;
-            this.writeState(state);
+            const existingSession = await this.ensureSession(registration, existingType, privateKey, forceSession);
+            const registered = await this.signedJSON("/v1/agent-instances", { agent_type: agentType }, registration, existingType, existingSession, privateKey);
+            registration.agentInstances[agentType] = registered.agent_instance_id;
         }
-        const session = await this.ensureSession(state, agentType, privateKey);
-        return { state, agentType, session, privateKey };
+        return this.ensureSession(registration, agentType, privateKey, forceSession);
     }
-    async enroll(agentType) {
-        const pair = generateKeyPairSync("ed25519");
-        const publicJWK = pair.publicKey.export({ format: "jwk" });
+    async enroll(agentType, privateKey) {
+        const publicJWK = createPublicKey(privateKey).export({ format: "jwk" });
         if (!publicJWK.x)
             throw new Error("unable to export Ed25519 public key");
         const publicKey = Buffer.from(publicJWK.x, "base64url").toString("base64");
         const started = await this.publicJSON("/v1/agent-device-enrollments", { public_key: publicKey, agent_type: agentType });
         const proof = enrollmentProofMessage(started.agent_device_enrollment_id, started.challenge);
-        const verified = await this.publicJSON(`/v1/agent-device-enrollments/${encodeURIComponent(started.agent_device_enrollment_id)}/verify`, { challenge: started.challenge, signature: sign(null, Buffer.from(proof), pair.privateKey).toString("base64") });
-        const state = {
-            schemaVersion: "itpay.device.v1",
+        const verified = await this.publicJSON(`/v1/agent-device-enrollments/${encodeURIComponent(started.agent_device_enrollment_id)}/verify`, { challenge: started.challenge, signature: sign(null, Buffer.from(proof), privateKey).toString("base64") });
+        return {
             deviceID: verified.agent_device_id,
             deviceKeyID: verified.agent_device_key_id,
             quotaLineageID: verified.quota_lineage_id,
             agentInstances: { [verified.agent_type]: verified.agent_instance_id },
             sessions: {},
         };
-        this.writePrivateKey(pair.privateKey.export({ format: "pem", type: "pkcs8" }).toString());
-        this.writeState(state);
-        return { state, privateKey: pair.privateKey };
     }
-    async ensureSession(state, agentType, privateKey) {
+    async ensureSession(state, agentType, privateKey, force = false) {
         const existing = state.sessions[agentType];
-        if (existing && Date.parse(existing.expiresAt) > Date.now() + 60_000)
+        if (!force && existing && Date.parse(existing.expiresAt) > Date.now() + 60_000)
             return existing;
         const instanceID = state.agentInstances[agentType];
         if (!instanceID)
@@ -107,7 +148,6 @@ export class DeviceAuthority {
         const verified = await this.publicJSON(`/v1/agent-device-session-challenges/${encodeURIComponent(challenge.agent_device_session_challenge_id)}/verify`, { challenge: challenge.challenge, signature: sign(null, Buffer.from(proof), privateKey).toString("base64") });
         const session = { token: verified.session_token, expiresAt: verified.expires_at };
         state.sessions[agentType] = session;
-        this.writeState(state);
         return session;
     }
     async signedJSON(path, bodyValue, state, agentType, session, privateKey) {
@@ -137,16 +177,26 @@ export class DeviceAuthority {
         });
         const payload = await response.json().catch(() => ({}));
         if (!response.ok)
-            throw new Error(payload.message || payload.code || `ItPay device request failed: ${response.status}`);
+            throw new DeviceAuthorizationError(response.status, payload.code, payload.message || payload.code || `ItPay device request failed: ${response.status}`);
         return payload;
     }
     readState() {
         if (!existsSync(this.statePath))
             return undefined;
         try {
-            return JSON.parse(readFileSync(this.statePath, "utf8"));
+            const parsed = JSON.parse(readFileSync(this.statePath, "utf8"));
+            if (parsed.schemaVersion === "itpay.device.v2")
+                return parsed;
+            if (parsed.schemaVersion === "itpay.device.v1") {
+                const { schemaVersion: _, ...legacyRegistration } = parsed;
+                return { ...emptyDeviceState(), legacyRegistration };
+            }
+            return undefined;
         }
-        catch {
+        catch (error) {
+            const stateError = asDeviceStateError(error, "read_state");
+            if (stateError)
+                throw stateError;
             return undefined;
         }
     }
@@ -156,62 +206,130 @@ export class DeviceAuthority {
         try {
             return createPrivateKey(readFileSync(this.privateKeyPath, "utf8"));
         }
-        catch {
+        catch (error) {
+            const stateError = asDeviceStateError(error, "read_private_key");
+            if (stateError)
+                throw stateError;
             return undefined;
         }
     }
-    writeState(state) { atomicOwnerOnlyWrite(this.statePath, JSON.stringify(state, null, 2)); }
-    writePrivateKey(value) { atomicOwnerOnlyWrite(this.privateKeyPath, value); }
+    writeState(state) { atomicOwnerOnlyWrite(this.statePath, JSON.stringify(state, null, 2), "write_state"); }
+    writePrivateKey(value) { atomicOwnerOnlyWrite(this.privateKeyPath, value, "write_private_key"); }
+}
+export class DeviceAuthorizationError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "DeviceAuthorizationError";
+    }
+}
+export class DeviceStateError extends Error {
+    operation;
+    causeCode;
+    code = "device_state_unwritable";
+    constructor(operation, causeCode) {
+        super(`ItPay device state operation failed: ${operation} (${causeCode})`);
+        this.operation = operation;
+        this.causeCode = causeCode;
+        this.name = "DeviceStateError";
+    }
+}
+function emptyDeviceState() {
+    return { schemaVersion: "itpay.device.v2", registrations: {} };
+}
+function firstAgentType(state) { return Object.keys(state.agentInstances)[0]; }
+function canMovePastLegacyRegistration(error) {
+    return error instanceof DeviceAuthorizationError && (error.code === "agent_device_revoked" || error.status === 404);
+}
+function normalizeBackendKey(value) {
+    const url = new URL(value);
+    url.search = "";
+    url.hash = "";
+    url.pathname = url.pathname.replace(/\/+$/, "");
+    return url.toString().replace(/\/$/, "");
 }
-function firstAgentType(state) { return state ? Object.keys(state.agentInstances)[0] : undefined; }
 function sha256(value) { return `sha256:${createHash("sha256").update(value).digest("hex")}`; }
 function enrollmentProofMessage(id, challenge) { return `itpay-device-enrollment/v1\n${id}\n${challenge}`; }
 function deviceSessionProofMessage(id, challenge) { return `itpay-device-session/v1\n${id}\n${challenge}`; }
 function requestProofMessage(method, path, bodyHash, timestamp, jti) { return ["itpay-agent-request/v1", method, path, bodyHash, timestamp, jti].join("\n"); }
-function atomicOwnerOnlyWrite(path, value) {
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+function atomicOwnerOnlyWrite(path, value, operation) {
     const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
-    writeFileSync(temporary, value, { encoding: "utf8", mode: 0o600 });
-    chmodSync(temporary, 0o600);
-    renameSync(temporary, path);
-    chmodSync(path, 0o600);
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(temporary, value, { encoding: "utf8", mode: 0o600 });
+        chmodSync(temporary, 0o600);
+        renameSync(temporary, path);
+        chmodSync(path, 0o600);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch { /* best-effort cleanup */ }
+        throw asDeviceStatePathError(error, operation) ?? error;
+    }
 }
 async function withFileLock(path, run) {
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    let descriptor;
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    }
+    catch (error) {
+        throw asDeviceStatePathError(error, "prepare_lock") ?? error;
+    }
+    let acquired = false;
     for (let attempt = 0; attempt < 200; attempt += 1) {
         try {
-            descriptor = openSync(path, "wx", 0o600);
+            mkdirSync(path, { mode: 0o700 });
+            acquired = true;
             break;
         }
         catch (error) {
             const code = error.code;
             if (code !== "EEXIST")
-                throw error;
+                throw asDeviceStateError(error, "acquire_lock") ?? error;
             try {
                 if (Date.now() - statSync(path).mtimeMs > 30_000)
-                    unlinkSync(path);
+                    removeLock(path, "remove_stale_lock");
             }
             catch (statError) {
-                if (statError.code !== "ENOENT")
-                    throw statError;
+                if (statError.code !== "ENOENT") {
+                    throw asDeviceStateError(statError, "inspect_lock") ?? statError;
+                }
             }
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
     }
-    if (descriptor === undefined)
+    if (!acquired)
         throw new Error("timed out waiting for ItPay device identity lock");
     try {
         return await run();
     }
     finally {
-        closeSync(descriptor);
-        try {
+        removeLock(path, "release_lock");
+    }
+}
+function removeLock(path, operation) {
+    try {
+        if (statSync(path).isDirectory())
+            rmdirSync(path);
+        else
             unlinkSync(path);
-        }
-        catch (error) {
-            if (error.code !== "ENOENT")
-                throw error;
-        }
     }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw asDeviceStateError(error, operation) ?? error;
+    }
+}
+function asDeviceStateError(error, operation) {
+    const code = error.code;
+    return code === "EACCES" || code === "EPERM" || code === "EROFS" || code === "ENOTDIR" || code === "EISDIR"
+        ? new DeviceStateError(operation, code)
+        : undefined;
+}
+function asDeviceStatePathError(error, operation) {
+    const code = error.code;
+    return code === "EEXIST" ? new DeviceStateError(operation, code) : asDeviceStateError(error, operation);
 }

package/docs/agent/buyer/catalog-list.json

@@ -27,7 +27,8 @@
     "Read the variant IDs and prices from the output; do not invent them.",
     "Explain the customer journey from service_flow instead of presenting every variant as an unrelated service.",
     "State free quota, paid continuation price, email requirement, and claim purpose exactly as published; do not exaggerate or omit conditions.",
-    "If the buyer wants to search by keyword, filter the catalog output client-side (no backend search yet)."
+    "If the buyer wants to search by keyword, filter the catalog output client-side (no backend search yet).",
+    "After services start, submit service keywords only through the returned capability command's --input key=value options; --target is never a search keyword."
   ],
   "next_docs": [
     {

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

@@ -0,0 +1,64 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "identity-and-sessions",
+  "title": "Device Identity And Session Recovery",
+  "purpose": "Explain stable local identity, Backend-scoped registrations, Agent Type instances, and bounded automatic session recovery.",
+  "when_to_use": [
+    "A different Agent window or runtime starts using an existing CLI installation.",
+    "The CLI reports device_state_unwritable, or the Backend reports agent_identity_required, agent_device_session_required, or agent_device_revoked.",
+    "The configured ITPAY_BACKEND_URL changes between dev, test, and app."
+  ],
+  "identity_model": {
+    "local_key": "One owner-only Ed25519 private key for the local installation.",
+    "backend_registration": "One independent server registration per normalized Backend API base URL.",
+    "agent_instance": "One instance per agent_type under each Backend registration; same-type windows and chats reuse it.",
+    "presentation": "Host and target route output only and never identify the Agent or provide business input."
+  },
+  "automatic_recovery": [
+    "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.",
+    "A revoked v2 registration requires explicit operator recovery; it is never silently replaced."
+  ],
+  "local_state_recovery": [
+    "Device state updates use an atomic directory lock and owner-only atomic file replacement; no lock file is opened with fs.open or fs.openSync.",
+    "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 manually create a lock, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
+  ],
+  "commands": [
+    {
+      "intent": "reload the complete rules",
+      "command": "itpay --agent-type <agent_type> skill show itpay-buyer --json",
+      "success_signal": "the full Skill is returned and next keeps the same Agent Type"
+    },
+    {
+      "intent": "confirm the selected Backend is available",
+      "command": "itpay --agent-type <agent_type> readyz --json",
+      "success_signal": "Backend is available and onboarding returns to the Skill"
+    },
+    {
+      "intent": "recover after an operator-confirmed reset of the selected Backend registration database",
+      "command": "itpay --agent-type <agent_type> device recover --confirm-backend-reset --json",
+      "success_signal": "only the selected Backend registration is removed; the private key and other Backend registrations remain"
+    }
+  ],
+  "agent_rules": [
+    "Use the real runtime type and keep it stable across every command in the flow.",
+    "Keep the same CLI/Node launcher and Host-approved permission context for the whole flow.",
+    "Treat a new window, chat, task, or process of the same runtime as the same Agent Type, not a new identity.",
+    "Expect dev, test, and app to have separate device IDs, quota lineage, Agent instances, and sessions even on the same machine.",
+    "After automatic recovery fails, stop and report the exact code, Backend URL, Agent Type, and command family without exposing private keys or tokens."
+  ],
+  "forbidden": [
+    "Do not delete ~/.itpay-v3, rotate the key, switch Agent Type, or repeatedly retry to obtain fresh quota.",
+    "Do not use device recover for session expiry, revocation, quota recovery, or an unconfirmed Backend failure.",
+    "Do not copy a server device ID from one Backend registration into another.",
+    "Do not use --target as identity or service input."
+  ],
+  "next_docs": [
+    { "condition": "Identity is healthy", "topic": "quickstart" },
+    { "condition": "Need setup details", "topic": "install-and-setup" }
+  ],
+  "search_terms": ["identity", "device", "session", "login", "authentication", "agent type", "backend", "revoked", "recover", "unwritable", "lock", "window", "chat"]
+}

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

@@ -3,12 +3,22 @@
   "role": "buyer",
   "topic": "install-and-setup",
   "title": "Install And Identify The ItPay Agent Runtime",
-  "purpose": "Install the CLI and select one of the five supported Agent Types without confusing Agent Type with Host.",
+  "purpose": "Install the CLI, load the complete Buyer Skill, and select one stable Agent Type without confusing identity, Backend, Host, target, or chat window.",
   "when_to_use": [
     "The CLI is being installed or upgraded.",
     "The agent needs to confirm its stable runtime identity and default output Host."
   ],
   "commands": [
+    {
+      "intent": "verify the API and enter packaged onboarding",
+      "command": "itpay readyz --json",
+      "success_signal": "status is ready and next points to skill show itpay-buyer"
+    },
+    {
+      "intent": "read the complete packaged operating contract",
+      "command": "itpay skill show itpay-buyer --json",
+      "success_signal": "status is shown, result.content contains the complete Skill, and next selects Agent Type or Catalog"
+    },
     {
       "intent": "list supported Agent Types",
       "command": "itpay install --json",
@@ -24,15 +34,19 @@
     "Install with npm install -g @itpay/cli.",
     "Use the default https://app.itpay.ai API unless an environment override is deliberate.",
     "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, or workbuddy.",
-    "Agent Type identifies the runtime and device instance. Host only controls human-facing rendering.",
-    "Do not change Agent Type to reset quota or recover a failed command."
+    "One local private key is reused, but each exact Backend API base URL has its own server registration and quota lineage.",
+    "Within one Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",
+    "Agent Type identifies the runtime. Host controls rendering and target only identifies a presentation destination.",
+    "Keep the exact Agent Type in every next or recovery command; do not fall back to a type previously used by another runtime.",
+    "Do not change Agent Type or rotate local identity to reset quota or recover a failed command."
   ],
   "forbidden": [
     "Do not use codex, terminal, claude-code, or plain-chat as Agent Types.",
-    "Do not claim that install writes host configuration or registers a device; it only prints instructions."
+    "Do not claim that install writes host configuration or registers a device; it only prints instructions.",
+    "Do not create a new identity for a different window, task, chat, or process of the same Agent Type."
   ],
   "next_docs": [
     { "condition": "Installation is verified", "topic": "quickstart" }
   ],
-  "search_terms": ["install", "agent type", "host", "codex", "claude code", "workbuddy"]
+  "search_terms": ["install", "agent type", "host", "target", "device", "session", "identity", "backend", "codex", "claude code", "workbuddy"]
 }

package/docs/agent/buyer/payment-flow.json

@@ -28,13 +28,17 @@
   "agent_rules": [
     "Normal buyer flow opens the ItPay Checkout page; itpay pay and buy --pay are operator escape hatches.",
     "Use only handoff fields returned for the current Host and make them actually visible to the human.",
+    "Before creating a single-Service Checkout, send the exact price confirmation requested by the current instruction, stop, and wait for explicit human agreement.",
+    "After presenting a Checkout, stop. Run the returned next.command only after the human completes the payment action or asks to query the same Checkout.",
     "Payment is verified only by Backend Checkout or Order state, never by QR rendering, redirect, or user claim.",
     "A terminal payment state must never display another payment handoff."
   ],
   "forbidden": [
     "Do not render a provider QR in place of the ItPay Checkout handoff.",
     "Do not mix a display token from another Checkout.",
-    "Do not create a replacement Checkout after an uncertain response; recover first."
+    "Do not create a replacement Checkout after an uncertain response; recover first.",
+    "Do not use services quote, cart, buy, or pay as a fallback when the single-Service checkout flow fails.",
+    "Do not start another Service Execution to bypass quota, candidate, quote, checkout, or delivery state."
   ],
   "next_docs": [
     { "condition": "Payment is verified", "topic": "orders-refunds" },

package/docs/agent/buyer/quickstart.json

@@ -19,7 +19,12 @@
     {
       "intent": "verify compatibility",
       "command": "itpay --agent-type <agent_type> readyz --json",
-      "success_signal": "status is ready and next points to catalog list"
+      "success_signal": "status is ready and next points to the complete packaged Buyer Skill"
+    },
+    {
+      "intent": "load the complete operating contract",
+      "command": "itpay --agent-type <agent_type> skill show itpay-buyer --json",
+      "success_signal": "status is shown and next points to catalog list with the same Agent Type"
     },
     {
       "intent": "discover published services",
@@ -45,7 +50,9 @@
   "agent_rules": [
     "Use the CLI as the control surface; do not call ItPay APIs directly or hardcode a service workflow.",
     "Treat result as current facts, instruction as how to use those facts, next as the preferred executable action, and recovery as exceptional paths.",
-    "Run one state-changing command at a time and execute the exact next.command unchanged after filling only required user data.",
+    "Run one state-changing command at a time. Treat next.command as the preferred continuation: execute it unchanged after filling required user data only when the current result has not already satisfied the user's goal.",
+    "Keep the same explicit Agent Type through next and recovery commands; same-type windows reuse one Backend Agent Instance.",
+    "Use --target only for a Host presentation destination. Put capability business values in --input key=value exactly as required by the schema.",
     "Start a separate Service Execution for each independent service intent; quota remains shared according to Backend identity policy.",
     "Ask the user for required email or contact values and explain their purpose; never invent them.",
     "Agent-visible delivery is returned by services next. Protected delivery is read only by services read-result while a human grant is active.",
@@ -63,7 +70,8 @@
     { "condition": "Need payment recovery", "topic": "payment-flow" },
     { "condition": "Need Host-specific presentation", "topic": "render-hosts" },
     { "condition": "Need order or refund recovery", "topic": "orders-refunds" },
-    { "condition": "Need install details", "topic": "install-and-setup" }
+    { "condition": "Need install or identity details", "topic": "install-and-setup" },
+    { "condition": "Need device session recovery rules", "topic": "identity-and-sessions" }
   ],
-  "search_terms": ["quickstart", "service", "next", "recovery", "delivery", "refund"]
+  "search_terms": ["quickstart", "service", "next", "recovery", "delivery", "refund", "target", "input"]
 }

package/docs/cli-reference/agent-types.md

@@ -1,6 +1,8 @@
 # Agent Type And Host Contract
 
-`--agent-type` 表示谁在运行 CLI，用于设备登记、Agent 实例归属和定制 instruction。`--host` 表示输出展示在哪里，用于选择二维码、链接或消息的渲染方式。两者不可混用。
+`--agent-type` 表示哪类运行时在运行 CLI，用于 Agent 实例归属和定制 instruction。`--host` 表示输出展示在哪里；`--target` 只是在某些 Host 中指定 chat/channel/open ID。三者不可混用，窗口、任务和对话也不是身份。
+
+本地只保存一把 Ed25519 私钥。每个规范化 Backend API base URL 独立登记 Device，因此 dev/test/app 分别拥有自己的 device ID、quota lineage、Agent instances 和 sessions。同一 Backend 下每个 `agent_type` 只有一个 Agent Instance；同类型的不同窗口、任务或聊天复用它，不追踪窗口 ID。
 
 ## 首批支持类型
 
@@ -15,10 +17,14 @@
 ## 通用规则
 
 - commerce 命令必须传 `--agent-type` 或设置 `ITPAY_AGENT_TYPE`。
-- Agent Type 必须稳定；同一运行时不得临时换名。
+- Agent Type 必须真实且稳定；同类型窗口复用同一实例，不得临时换名。
+- `next.command` 和 `recovery.command` 必须保留当前显式 Agent Type，不读取或回退到机器上其他类型。
 - 显式 `--host` 覆盖默认 Host，但不改变已登记的 Agent Type。
+- `--target` 只路由人类展示，不是身份，也不是 capability 业务输入。
 - Host 只影响 `instruction` 和 `handoff`，不得改变金额、订单、权限、quota 或交付状态。
-- 非展示命令在五种 Agent Type 下返回相同业务结果，只允许 instruction 措辞不同。
+- 五种 Agent Type 使用同一命令输入和 JSON 外壳；不得为单个 Agent Type 新增、删除或改名协议字段。
+- 非展示命令在五种 Agent Type 下返回相同业务结果，只允许 `instruction` 措辞不同。只有 Host 客观无法展示某种媒介时，`handoff` 才按既有可选字段做最小裁剪。
+- session 失效时 CLI 只续期并重试原请求一次；再次失败立即返回。revoked v2 Device 不自动换身份。
 
 ## Checkout Handoff 最小合同
 

package/docs/cli-reference/commands/catalog/list.md

@@ -31,7 +31,7 @@ itpay catalog list [--json]
     ]
   },
   "instruction": "向用户解释主服务、辅助步骤和价格；得到用户意图后再启动对应 service_id。",
-  "next": { "command": "itpay services start <service_id>", "reason": "启动用户选择的服务" },
+  "next": { "command": "itpay --agent-type <agent_type> services start <service_id> --json", "reason": "启动用户选择的服务" },
   "recovery": []
 }
 ```

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

@@ -25,8 +25,8 @@ itpay checkout [--id <checkout_id>] [--token <display_token>]
   "status": "human_checkout_required",
   "result": { "checkout_id": "<checkout_id>", "payment": "pending", "amount": "<amount> <currency>" },
   "handoff": { "url": "<checkout_url>", "qr_local_path": "<host_optional_path>", "markdown": "<desktop_optional_markdown>" },
-  "instruction": "把当前 Host 的二维码和付款链接展示给用户，然后等待用户操作；不要创建新 Checkout。",
-  "next": { "command": "itpay checkout --id <checkout_id> --token <display_token>", "reason": "稍后查询同一笔 Checkout 状态" },
+  "instruction": "Backend 尚未确认付款。把当前同一 Checkout 的付款入口重新展示给用户，然后停止等待。不要声称付款成功，不要创建新 Checkout、Execution 或 Payment Intent。稍后仍然只执行 next.command 查询这一笔 Checkout。",
+  "next": { "command": "itpay checkout --id <checkout_id> --token <display_token> --json", "reason": "稍后只查询同一 Checkout" },
   "recovery": []
 }
 ```
@@ -37,8 +37,8 @@ itpay checkout [--id <checkout_id>] [--token <display_token>]
 {
   "status": "completed",
   "result": { "checkout_id": "<checkout_id>", "payment": "verified", "order_id": "<optional_order_id>", "service_execution_id": "<optional_id>" },
-  "instruction": "付款已确认，不要再次展示付款二维码。",
-  "next": { "command": "itpay services next <service_execution_id> --json", "reason": "读取履约状态" },
+  "instruction": "Backend 已确认这笔付款。不要再次展示付款入口，不要调用 pay，不要创建新 Checkout 或 Execution。现在只执行 next.command，读取同一 Execution 的履约结果。",
+  "next": { "command": "itpay services next <service_execution_id> --json", "reason": "读取同一笔已付款 Service Execution" },
   "recovery": []
 }
 ```

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

@@ -0,0 +1,13 @@
+# `itpay device recover`
+
+## 范围
+
+仅在运营明确确认当前 Backend 的 Device 登记数据库已重建或清空后，删除本地该 Backend 的 v2 registration：
+
+```bash
+itpay --agent-type <agent_type> device recover --confirm-backend-reset --json
+```
+
+命令使用 `ITPAY_BACKEND_URL` 选择唯一作用域，保留本地 Ed25519 私钥、其他 Backend registrations、Cart 和业务资源。它不访问 Backend，不自动创建新身份；返回的只读 `services list` 是重新登记入口。
+
+缺少确认参数返回 `backend_reset_confirmation_required`。普通 session 失效由 CLI 自动续期；revoked、quota、权限或未知 Backend 故障不得使用本命令。所有 Agent Type 使用相同输入和输出合同。

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

@@ -6,7 +6,7 @@
 
 **上游：** 安装或更新 `@itpay/cli`。
 
-**下游：** 使用真实 Agent Type 执行 `readyz`，随后读取 Catalog。
+**下游：** 使用真实 Agent Type 执行 `readyz`，随后读取完整 Skill 和 Catalog。
 
 ## 语法与参数
 
@@ -87,6 +87,8 @@ itpay install [target] [--json]
 
 显式 `--host` 可以在后续 commerce 命令覆盖默认 Host，但不会改变 Agent Type 或设备归属。
 
+同一类型的不同窗口、任务和聊天复用当前 Backend 下的同一个 Agent Instance。切换 Backend 会在同一本地私钥下建立独立服务端登记，不会把 dev/test/app 的 Device ID 混用。
+
 ## 异常处理
 
 未知 target 返回：

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

@@ -5,7 +5,7 @@
 检查当前配置的 ItPay API 是否可用。它只做环境诊断，不登记设备、不创建业务资源。
 
 **上游：** CLI 安装和 Backend URL 配置。
-**下游：** `catalog list` 或失败后的网络/配置修复。
+**下游：** 完整 `itpay-buyer` Skill，随后选择 Agent Type 或读取 Catalog。
 
 ## 语法与参数
 
@@ -23,8 +23,8 @@ itpay readyz [--json]
 {
   "status": "ready",
   "result": { "backend": "available" },
-  "instruction": "ItPay 可用，可以读取服务目录。",
-  "next": { "command": "itpay catalog list", "reason": "发现可用服务" },
+  "instruction": "ItPay 可用；先完整读取内置 Buyer Skill，再开始服务流程。",
+  "next": { "command": "itpay skill show itpay-buyer --json", "reason": "加载完整操作与安全规则" },
   "recovery": []
 }
 ```
@@ -35,5 +35,4 @@ itpay readyz [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 行为相同；本命令不渲染 Host 内容。
-
+本命令不渲染 Host 内容。若已声明 Agent Type，`result.agent_type` 会确认该类型，且返回的 Skill 命令保留同一 `--agent-type`；未声明时 Skill 会先引导 `install`。