@awiki/dsh-plugin 0.3.10 → 0.3.11-rc.2

package/lib/types/client/controller.js

@@ -1,6 +1,33 @@
 import { AwikiDraftStore } from "./drafts.js";
+import { SHORT_HANDLE_INVITE_MESSAGE } from "../registration-policy.js";
 import { IndexedDbAwikiBrowserImageCache, } from "./image-cache.js";
 import { clearMailBrowserCache } from "./mail-list-cache.js";
+const GENERIC_BUSINESS_FAILURE_MESSAGE = 'AWiki 暂时无法完成此操作，请稍后重试。';
+const GENERIC_CARRIER_FAILURE_MESSAGE = '暂时无法连接 AWiki Host，请稍后重试。';
+const GENERIC_THROW_FAILURE_MESSAGE = 'AWiki 调用暂时失败，请稍后重试。';
+/** Project only a stable business code into Browser copy; provider messages remain Host-only. */
+function genericFailureMessage(failure) {
+    switch (failure.code) {
+        case 'network':
+            return '无法连接 AWiki 服务，请检查网络后重试。';
+        case 'rate-limited':
+            return 'AWiki 请求过于频繁，请稍后重试。';
+        case 'not-registered':
+            return '请先注册 AWiki 身份后重试。';
+        case 'signed-out':
+            return '当前 AWiki 身份已退出，请重新进入后重试。';
+        case 'identity-recovery-required':
+            return '当前设备的 AWiki 身份凭证已失效，请重新恢复身份。';
+        case 'device-rejoin-required':
+            return '当前设备已被撤销，请重新申请加入。';
+        default:
+            return GENERIC_BUSINESS_FAILURE_MESSAGE;
+    }
+}
+/** Carrier diagnostics are not a Browser contract, including for unknown carrier codes. */
+function genericCarrierFailureMessage(_failure) {
+    return GENERIC_CARRIER_FAILURE_MESSAGE;
+}
 /** Turn a registration rejection into an actionable message without exposing remote response text. */
 function registrationFailureMessage(failure) {
     switch (failure.code) {
@@ -14,6 +41,8 @@ function registrationFailureMessage(failure) {
             return '验证码状态已失效，请重新获取验证码后再注册。';
         case 'handle-unavailable':
             return '该 Handle 刚刚已被注册。请返回身份入口，再按恢复流程重新获取验证码。';
+        case 'short-handle-invite-required':
+            return SHORT_HANDLE_INVITE_MESSAGE;
         case 'conflict':
             return '注册冲突：服务端可能已收到上次注册请求，或该手机号 / Handle 已绑定其他身份。请保留当前页面并再次提交；若仍失败，请勿清除本机身份数据，联系管理员并提供失败时间。';
         case 'rate-limited':
@@ -27,12 +56,14 @@ function registrationFailureMessage(failure) {
         case 'remote':
             return 'AWiki 服务暂时无法完成注册，请稍后重试；若持续失败，请联系管理员并提供失败时间。';
         default:
-            return `${failure.code}：${failure.message}`;
+            return 'AWiki 服务暂时无法完成注册，请稍后重试；若持续失败，请联系管理员并提供失败时间。';
     }
 }
 /** Turn a verification-code request failure into a safe next action. */
 function registrationOtpFailureMessage(failure) {
     switch (failure.code) {
+        case 'short-handle-invite-required':
+            return SHORT_HANDLE_INVITE_MESSAGE;
         case 'rate-limited':
             return '验证码发送过于频繁，请等待限流解除后再重新获取。';
         case 'invalid-request':
@@ -62,7 +93,7 @@ function recoveryPreparationFailureMessage(failure) {
         case 'remote':
             return 'AWiki 服务暂时无法验证恢复信息，请稍后重试。';
         default:
-            return `${failure.code}：${failure.message}`;
+            return 'AWiki 服务暂时无法验证恢复信息，请稍后重试。';
     }
 }
 function recoveryContinuationFailureMessage(failure, phase) {
@@ -84,7 +115,7 @@ function recoveryContinuationFailureMessage(failure, phase) {
         case 'forbidden':
             return 'AWiki 服务暂时未能完成恢复。可以重新检查结果，或返回入口稍后继续。';
         default:
-            return `${failure.code}：${failure.message}`;
+            return '身份恢复暂未完成。请保留当前恢复操作并重新检查状态，不要重新获取验证码或创建新身份。';
     }
 }
 function identityAccessInspectionFailureMessage(failure) {
@@ -96,9 +127,10 @@ function identityAccessInspectionFailureMessage(failure) {
         case 'remote':
             return 'AWiki 服务暂时无法确认该 Handle 的状态，请稍后重试。';
         default:
-            return `${failure.code}：${failure.message}`;
+            return 'AWiki 服务暂时无法确认该 Handle 的状态，请稍后重试。';
     }
 }
+const IDENTITY_ACCESS_FAILURE_MESSAGE = '暂时无法读取本机身份状态，请稍后重新检查。';
 const INITIAL_VIEW = Object.freeze({
     status: 'cold',
     sessionStatus: 'unregistered',
@@ -126,6 +158,7 @@ const INITIAL_VIEW = Object.freeze({
     accessError: null,
     recoveryOperationId: null,
     recoveryProgress: null,
+    recoveryOtpRetryAt: null,
 });
 /** Turn a closed Host summary failure into one actionable Chinese message. */
 function summaryFailureMessage(failure) {
@@ -135,7 +168,7 @@ function summaryFailureMessage(failure) {
         case 'summary-cancelled': return 'AI 总结已取消，请重新生成。';
         case 'summary-invalid-output': return '模型没有返回有效的结构化摘要，请重新生成。';
         case 'summary-failed': return '暂时无法生成 AI 总结，请检查模型连接后重试。';
-        default: return `${failure.code}：${failure.message}`;
+        default: return '暂时无法生成 AI 总结，请检查模型连接后重试。';
     }
 }
 /** Turn closed mail failures into safe, actionable browser messages. */
@@ -163,7 +196,7 @@ function groupCreateFailureMessage(failure) {
         case 'network': return '无法连接 AWiki 服务，请检查网络后重试。';
         case 'conflict': return '群聊创建状态发生冲突，请刷新群聊列表后确认是否已经创建。';
         case 'remote': return 'AWiki 服务暂时无法创建群聊，请稍后重试。';
-        default: return `${failure.code}：${failure.message}`;
+        default: return 'AWiki 服务暂时无法创建群聊，请稍后重试。';
     }
 }
 /** Keep group authorization failures actionable without exposing raw service text. */
@@ -182,7 +215,7 @@ function groupReadFailureMessage(failure) {
         case 'remote':
             return 'AWiki 暂时无法读取这个群聊，请稍后重试。';
         default:
-            return `${failure.code}：${failure.message}`;
+            return 'AWiki 暂时无法读取这个群聊，请稍后重试。';
     }
 }
 function conversationPreferenceFailureMessage(_failure) {
@@ -217,21 +250,18 @@ async function callGroupRead(operation) {
     }
 }
 /** Flatten the carrier and business result once for every controller caller. */
-async function call(operation, failureMessage = failure => `${failure.code}：${failure.message}`, carrierFailureMessage = message => `连接 AWiki Host 失败：${message}`) {
+async function call(operation, failureMessage = genericFailureMessage, carrierFailureMessage = genericCarrierFailureMessage) {
     try {
         const carried = await operation();
         if (!carried.ok)
-            return { ok: false, error: carrierFailureMessage(carried.error.message) };
+            return { ok: false, error: carrierFailureMessage(carried.error) };
         if (!carried.value.ok) {
             return { ok: false, error: failureMessage(carried.value.error) };
         }
         return { ok: true, value: carried.value.value };
     }
-    catch (error) {
-        return {
-            ok: false,
-            error: error instanceof Error ? `AWiki 调用失败：${error.message}` : 'AWiki 调用失败',
-        };
+    catch {
+        return { ok: false, error: GENERIC_THROW_FAILURE_MESSAGE };
     }
 }
 /** Flatten the carrier and the isolated Guest Integration business result. */
@@ -239,9 +269,22 @@ async function callIntegration(operation) {
     try {
         const carried = await operation();
         if (!carried.ok)
-            return { ok: false, error: `连接 AWiki Host 失败：${carried.error.message}` };
-        if (!carried.value.ok)
-            return { ok: false, error: carried.value.error.message };
+            return { ok: false, error: genericCarrierFailureMessage(carried.error) };
+        if (!carried.value.ok) {
+            const failure = carried.value.error;
+            const error = failure.code === 'not-found'
+                ? '尚未创建 Integration。'
+                : failure.code === 'conflict'
+                    ? 'Integration 已在其他位置更新，请重新加载后再试。'
+                    : failure.code === 'invalid-request'
+                        ? 'Integration 信息不完整或格式不正确。'
+                        : failure.code === 'unauthorized' || failure.code === 'forbidden'
+                            ? '当前 AWiki 身份无权管理此 Integration。'
+                            : failure.code === 'rate-limited'
+                                ? 'Integration 操作过于频繁，请稍后重试。'
+                                : '临时消息服务暂时不可用，请稍后重试。';
+            return { ok: false, error, failureCode: failure.code };
+        }
         return { ok: true, value: carried.value.value };
     }
     catch {
@@ -249,31 +292,28 @@ async function callIntegration(operation) {
     }
 }
 /** Preserve only the stable business code for controller-level state transitions. */
-async function callWithFailureCode(operation) {
+async function callWithFailureCode(operation, failureMessage = genericFailureMessage) {
     try {
         const carried = await operation();
         if (!carried.ok)
-            return { ok: false, error: `连接 AWiki Host 失败：${carried.error.message}` };
+            return { ok: false, error: genericCarrierFailureMessage(carried.error) };
         if (!carried.value.ok) {
             return {
                 ok: false,
-                error: `${carried.value.error.code}：${carried.value.error.message}`,
+                error: failureMessage(carried.value.error),
                 failureCode: carried.value.error.code,
             };
         }
         return { ok: true, value: carried.value.value };
     }
-    catch (error) {
-        return {
-            ok: false,
-            error: error instanceof Error ? `AWiki 调用失败：${error.message}` : 'AWiki 调用失败',
-        };
+    catch {
+        return { ok: false, error: GENERIC_THROW_FAILURE_MESSAGE };
     }
 }
-function recoveryCarrierFailureMessage(message) {
-    return message.includes('business result failed boundary validation')
+function recoveryCarrierFailureMessage(failure) {
+    return failure.code === 'invalid-response'
         ? '恢复信息已验证，但暂时无法读取恢复状态。请稍后重试。'
-        : `连接 AWiki Host 失败：${message}`;
+        : '暂时无法连接 AWiki Host，无法完成身份恢复。请稍后重试。';
 }
 /** Append unique values while retaining existing references. */
 function appendUnique(current, incoming, id) {
@@ -373,11 +413,15 @@ const GROUP_HISTORY_RETRY_DELAYS_MS = [250, 750, 1_500, 2_500];
 /** Runtime-only decoded-byte budget that prevents repeat Host calls while browsing. */
 const BROWSER_IMAGE_ATTACHMENT_CACHE_MAX_BYTES = 32 * 1024 * 1024;
 const RECOVERY_OPERATION_STORAGE_KEY = 'awiki.handle-recovery.operation.v1';
+const RECOVERY_OTP_RETRY_STORAGE_KEY = 'awiki.handle-recovery.retry-at.v1';
 function recoveryOperationStorageKey(tenantId) {
     return tenantId === undefined || tenantId === ''
         ? RECOVERY_OPERATION_STORAGE_KEY
         : `${RECOVERY_OPERATION_STORAGE_KEY}.${encodeURIComponent(tenantId)}`;
 }
+function recoveryTenantKey(tenantId) {
+    return tenantId === undefined || tenantId === '' ? 'default' : tenantId;
+}
 function storeRecoveryOperation(operationId, tenantId) {
     try {
         const key = recoveryOperationStorageKey(tenantId);
@@ -390,6 +434,49 @@ function storeRecoveryOperation(operationId, tenantId) {
         // Recovery remains durable in Core even when browser storage is unavailable.
     }
 }
+function recoveryOtpRetryStorageKey(operationId, tenantId) {
+    return `${RECOVERY_OTP_RETRY_STORAGE_KEY}.${encodeURIComponent(recoveryTenantKey(tenantId))}.${encodeURIComponent(operationId)}`;
+}
+function recoveryOtpRetryAt(result) {
+    const advertised = Date.parse(result.retryAt);
+    const deadline = Number.isFinite(advertised)
+        ? advertised
+        : Date.now() + Math.max(0, result.retryAfterSeconds) * 1_000;
+    return new Date(deadline).toISOString();
+}
+function storedRecoveryOtpRetryAt(operationId, tenantId) {
+    if (operationId === null)
+        return null;
+    try {
+        const key = recoveryOtpRetryStorageKey(operationId, tenantId);
+        const value = globalThis.localStorage?.getItem(key);
+        if (value === null || value === undefined)
+            return null;
+        const deadline = Date.parse(value);
+        if (!Number.isFinite(deadline) || deadline <= Date.now()) {
+            globalThis.localStorage?.removeItem(key);
+            return null;
+        }
+        return new Date(deadline).toISOString();
+    }
+    catch {
+        return null;
+    }
+}
+function storeRecoveryOtpRetryAt(operationId, retryAt, tenantId) {
+    try {
+        globalThis.localStorage?.setItem(recoveryOtpRetryStorageKey(operationId, tenantId), retryAt);
+    }
+    catch { }
+}
+function clearRecoveryOtpRetryAt(operationId, tenantId) {
+    if (operationId === null)
+        return;
+    try {
+        globalThis.localStorage?.removeItem(recoveryOtpRetryStorageKey(operationId, tenantId));
+    }
+    catch { }
+}
 /** Wait between group-history readiness probes without retaining controller state. */
 function delay(milliseconds) {
     return new Promise(resolve => setTimeout(resolve, milliseconds));
@@ -439,6 +526,8 @@ export class AwikiController {
     drafts = new AwikiDraftStore();
     view = INITIAL_VIEW;
     listeners = new Set();
+    /** Runtime-only selected operations survive tenant round trips without reopening stale browser hints after reload. */
+    recoveryOperationsByTenant = new Map();
     config = null;
     conversationsCursor;
     historyCursor;
@@ -521,6 +610,9 @@ export class AwikiController {
             && previous.sessionStatus === session.value.status && previous.identity?.did === identity?.did;
         this.drafts.setScope(config.value.tenantId ?? 'default', identity?.did ?? session.value.status);
         this.activatePresentationCache(identity);
+        const selectedRecovery = previousTenant === config.value.tenantId
+            ? previous.recoveryOperationId
+            : this.recoveryOperationsByTenant.get(recoveryTenantKey(config.value.tenantId)) ?? null;
         this.publish({
             ...(sameOwner ? this.view : INITIAL_VIEW),
             status: 'ready',
@@ -529,7 +621,8 @@ export class AwikiController {
             error: null,
             attachmentMaxBytes: config.value.attachmentMaxBytes,
             handleRecoveryPhoneEnabled: config.value.handleRecoveryPhoneEnabled,
-            recoveryOperationId: previousTenant === config.value.tenantId ? previous.recoveryOperationId : null,
+            recoveryOperationId: selectedRecovery,
+            recoveryOtpRetryAt: storedRecoveryOtpRetryAt(selectedRecovery, config.value.tenantId),
         });
         await this.refreshIdentityAccess();
         if (!this.current(generation))
@@ -684,7 +777,10 @@ export class AwikiController {
      * @returns challenge retry metadata or one display-safe failure.
      */
     async sendRegistrationOtp(request) {
-        return this.withPending('发送验证码', () => call(() => this.remote.sendRegistrationOtp(request), registrationOtpFailureMessage));
+        const result = await this.withPending('发送验证码', () => callWithFailureCode(() => this.remote.sendRegistrationOtp(request), registrationOtpFailureMessage));
+        return !result.ok && result.failureCode !== 'short-handle-invite-required'
+            ? { ok: false, error: result.error }
+            : result;
     }
     /** Discover Core-owned work without selecting an account or activating a session. */
     refreshIdentityAccess() {
@@ -705,28 +801,36 @@ export class AwikiController {
         if (!this.recoveryCurrent(generation, revision))
             return this.recoveryLeft();
         if (!result.ok) {
-            this.publish({ ...this.view, accessLoading: false, accessError: result.error });
-            return result;
+            this.publish({ ...this.view, accessLoading: false, accessError: IDENTITY_ACCESS_FAILURE_MESSAGE });
+            return { ok: false, error: IDENTITY_ACCESS_FAILURE_MESSAGE };
         }
         const candidates = result.value.recoveries;
         const selected = this.view.recoveryOperationId;
-        this.publish({ ...this.view, identityAccess: result.value });
+        this.publish({ ...this.view, identityAccess: result.value, recoveryOperationId: selected,
+            recoveryProgress: selected === this.view.recoveryOperationId ? this.view.recoveryProgress : null,
+            recoveryOtpRetryAt: storedRecoveryOtpRetryAt(selected, this.config?.tenantId) });
         if (selected !== null) {
             const status = await callWithFailureCode(() => this.remote.getRecoveryStatus({ operationId: selected }));
             if (!this.recoveryCurrent(generation, revision))
                 return this.recoveryLeft();
             if (!status.ok) {
                 if (status.failureCode === 'not-found' && candidates.length === 0) {
-                    storeRecoveryOperation(null, this.config?.tenantId);
-                    this.publish({ ...this.view, recoveryOperationId: null, recoveryProgress: null });
+                    clearRecoveryOtpRetryAt(selected, this.config?.tenantId);
+                    this.rememberRecoveryOperation(null, this.config?.tenantId);
+                    this.publish({ ...this.view, recoveryOperationId: null, recoveryProgress: null, recoveryOtpRetryAt: null });
                 }
                 else {
-                    this.publish({ ...this.view, accessLoading: false, accessError: status.error });
-                    return { ok: false, error: status.error };
+                    this.publish({ ...this.view, accessLoading: false, accessError: IDENTITY_ACCESS_FAILURE_MESSAGE });
+                    return { ok: false, error: IDENTITY_ACCESS_FAILURE_MESSAGE };
                 }
             }
             else {
-                this.publish({ ...this.view, recoveryProgress: status.value });
+                const complete = status.value.phase === 'applied';
+                if (complete)
+                    clearRecoveryOtpRetryAt(selected, this.config?.tenantId);
+                this.publish({ ...this.view, recoveryProgress: status.value,
+                    recoveryOtpRetryAt: complete ? null : storedRecoveryOtpRetryAt(selected, this.config?.tenantId),
+                    identityAccess: result.value });
             }
         }
         this.publish({ ...this.view, accessLoading: false, accessError: null });
@@ -740,7 +844,9 @@ export class AwikiController {
             this.leaveRecovery();
         else
             this.recoveryRevision++;
-        this.publish({ ...this.view, recoveryOperationId: operationId, recoveryProgress: null });
+        this.rememberRecoveryOperation(operationId, this.config?.tenantId);
+        this.publish({ ...this.view, recoveryOperationId: operationId, recoveryProgress: null,
+            recoveryOtpRetryAt: storedRecoveryOtpRetryAt(operationId, this.config?.tenantId) });
         const result = await this.refreshRecoveryStatus();
         return result.ok ? { ok: true, value: undefined } : result;
     }
@@ -752,6 +858,16 @@ export class AwikiController {
     recoveryLeft() {
         return { ok: false, error: '已离开此恢复流程；进度保留在本机。' };
     }
+    rememberRecoveryOperation(operationId, tenantId) {
+        const key = recoveryTenantKey(tenantId);
+        if (operationId === null) {
+            this.recoveryOperationsByTenant.delete(key);
+            storeRecoveryOperation(null, tenantId);
+        }
+        else {
+            this.recoveryOperationsByTenant.set(key, operationId);
+        }
+    }
     /** Navigation only. Never cancel or delete the Core-owned operation. */
     leaveRecovery() {
         this.recoveryRevision++;
@@ -761,7 +877,7 @@ export class AwikiController {
             this.pendingRequest = undefined;
         this.pendingRecovery = false;
         this.drafts.clearFlow();
-        storeRecoveryOperation(null, this.config?.tenantId);
+        this.rememberRecoveryOperation(null, this.config?.tenantId);
         this.publish({ ...this.view, recoveryOperationId: null, recoveryProgress: null, accessError: null,
             accessLoading: false, pending: wasPending ? null : this.view.pending, error: null });
     }
@@ -792,10 +908,16 @@ export class AwikiController {
      */
     async registerIdentity(request) {
         const generation = this.generation;
-        const result = await this.withPending('注册身份', () => call(() => this.remote.registerIdentity(request), registrationFailureMessage));
+        const classified = await this.withPending('注册身份', () => callWithFailureCode(() => this.remote.registerIdentity(request), registrationFailureMessage));
+        const result = !classified.ok && classified.failureCode !== 'short-handle-invite-required'
+            ? { ok: false, error: classified.error }
+            : classified;
         if (!result.ok) {
             if (this.current(generation))
                 await this.refreshIdentityAccess();
+            if (this.current(generation) && result.failureCode === 'short-handle-invite-required') {
+                this.publish({ ...this.view, error: null });
+            }
             return result;
         }
         if (!this.current(generation))
@@ -839,6 +961,68 @@ export class AwikiController {
             return result.ok ? { ok: true, value: undefined } : result;
         });
     }
+    /** Cancel one exact Join choice and send Recovery OTP only while its original browser scope remains current. */
+    async beginRecoveryFromDeviceJoin(request) {
+        const generation = this.generation;
+        const tenantId = this.config?.tenantId;
+        const flowScope = this.drafts.getScope('recovery:retryDeadline');
+        const flowEpoch = this.drafts.epoch(flowScope);
+        const changed = () => ({
+            ok: false,
+            error: '恢复能力或身份环境已改变，请重新检查后再选择。',
+        });
+        const scopeCurrent = () => this.current(generation)
+            && this.config?.tenantId === tenantId
+            && this.drafts.getScope('recovery:retryDeadline') === flowScope
+            && this.drafts.epoch(flowScope) === flowEpoch;
+        if (!scopeCurrent())
+            return changed();
+        const latest = await call(() => this.remote.getConfig());
+        if (!scopeCurrent())
+            return changed();
+        if (!latest.ok)
+            return { ok: false, error: '暂时无法确认服务器的恢复能力，请稍后重试。' };
+        if (latest.value.tenantId !== tenantId)
+            return changed();
+        this.config = latest.value;
+        this.publish({ ...this.view, handleRecoveryPhoneEnabled: latest.value.handleRecoveryPhoneEnabled });
+        if (latest.value.tenantOnline === false) {
+            return { ok: false, error: '暂时无法确认服务器的恢复能力，请稍后重试。' };
+        }
+        if (!latest.value.handleRecoveryPhoneEnabled) {
+            return { ok: false, error: '当前服务器未启用手机号恢复，请加入新设备或联系管理员。' };
+        }
+        const current = () => scopeCurrent() && this.config?.handleRecoveryPhoneEnabled === true;
+        const result = await this.withPending('开始恢复身份', async () => {
+            const discarded = await call(() => this.remote.cancelDeviceJoin());
+            if (!discarded.ok)
+                return discarded;
+            if (!current())
+                return changed();
+            this.publish({ ...this.view, identityAccess: { choice: null, joining: false, recoveries: [] } });
+            if (request.phone === '')
+                return { ok: true, value: null };
+            return call(() => this.remote.sendRecoveryOtp(request), registrationOtpFailureMessage);
+        }, { publishFailure: false, recovery: true });
+        if (!result.ok) {
+            if (current())
+                await this.continueRecoveryForHandle(request.fullHandle);
+            return result;
+        }
+        if (result.value === null)
+            return result;
+        this.recordRecoveryOtp(result.value, tenantId);
+        const sameFlow = this.config?.tenantId === tenantId
+            && this.drafts.getScope('recovery:retryDeadline') === flowScope
+            && this.drafts.epoch(flowScope) === flowEpoch;
+        if (!sameFlow)
+            return result;
+        const retryAt = recoveryOtpRetryAt(result.value);
+        this.publish({ ...this.view, recoveryOperationId: result.value.operationId, recoveryProgress: null,
+            recoveryOtpRetryAt: retryAt });
+        await this.refreshRecoveryStatus();
+        return result;
+    }
     retireDeviceIdentityForRejoin() {
         return this.withPending('准备重新加入设备', async () => {
             const result = await call(() => this.remote.retireDeviceIdentityForRejoin());
@@ -912,17 +1096,29 @@ export class AwikiController {
     async sendRecoveryOtp(request) {
         const generation = this.generation;
         const revision = this.recoveryRevision;
+        const tenantId = this.config?.tenantId;
+        const flowScope = this.drafts.getScope('recovery:retryDeadline');
         const result = await this.withPending('发送恢复验证码', () => call(() => this.remote.sendRecoveryOtp(request), registrationOtpFailureMessage), { publishFailure: false, recovery: true });
-        if (!this.recoveryCurrent(generation, revision))
-            return this.recoveryLeft();
         if (!result.ok) {
+            if (!this.recoveryCurrent(generation, revision))
+                return this.recoveryLeft();
             await this.continueRecoveryForHandle(request.fullHandle);
             return result;
         }
-        this.publish({ ...this.view, recoveryOperationId: result.value.operationId, recoveryProgress: null });
+        this.recordRecoveryOtp(result.value, tenantId);
+        if (!this.recoveryCurrent(generation, revision)
+            || this.config?.tenantId !== tenantId
+            || this.drafts.getScope('recovery:retryDeadline') !== flowScope)
+            return result;
+        this.publish({ ...this.view, recoveryOperationId: result.value.operationId, recoveryProgress: null,
+            recoveryOtpRetryAt: recoveryOtpRetryAt(result.value) });
         await this.refreshRecoveryStatus();
         return this.recoveryCurrent(generation, revision) ? result : this.recoveryLeft();
     }
+    recordRecoveryOtp(result, tenantId) {
+        this.rememberRecoveryOperation(result.operationId, tenantId);
+        storeRecoveryOtpRetryAt(result.operationId, recoveryOtpRetryAt(result), tenantId);
+    }
     /** Publish results only into the exact selected flow; Core work survives navigation. */
     async runRecovery(label, operation, enterWhenApplied = false) {
         const generation = this.generation;
@@ -935,14 +1131,16 @@ export class AwikiController {
             return this.recoveryLeft();
         if (!result.ok) {
             // Reconcile authority after an ambiguous failure, never infer whether Commit occurred.
-            const status = await call(() => this.remote.getRecoveryStatus({ operationId }));
+            const status = await call(() => this.remote.getRecoveryStatus({ operationId }), undefined, recoveryCarrierFailureMessage);
             if (!this.recoveryCurrent(generation, revision))
                 return this.recoveryLeft();
             this.publish({ ...this.view, recoveryProgress: status.ok ? status.value : this.view.recoveryProgress,
-                accessError: status.ok ? null : status.error });
+                accessError: status.ok ? null : IDENTITY_ACCESS_FAILURE_MESSAGE });
             return result;
         }
         this.publish({ ...this.view, recoveryProgress: result.value, accessError: null });
+        if (result.value.phase === 'applied')
+            clearRecoveryOtpRetryAt(operationId, this.config?.tenantId);
         if (enterWhenApplied && result.value.phase === 'applied')
             return this.enterRecoveredSession();
         return result;
@@ -960,7 +1158,25 @@ export class AwikiController {
     }
     /** Read-only even for applied operations. Entering the identity is a separate action. */
     async refreshRecoveryStatus() {
-        return this.runRecovery('刷新恢复状态', operationId => call(() => this.remote.getRecoveryStatus({ operationId }), undefined, recoveryCarrierFailureMessage));
+        const generation = this.generation;
+        const revision = this.recoveryRevision;
+        const operationId = this.view.recoveryOperationId;
+        if (operationId === null)
+            return { ok: false, error: '没有可查询的身份恢复操作' };
+        const result = await this.withPending('刷新恢复状态', async () => {
+            const status = await call(() => this.remote.getRecoveryStatus({ operationId }), undefined, recoveryCarrierFailureMessage);
+            return status.ok ? status : { ok: false, error: IDENTITY_ACCESS_FAILURE_MESSAGE };
+        }, { publishFailure: false, recovery: true });
+        if (!this.recoveryCurrent(generation, revision))
+            return this.recoveryLeft();
+        if (!result.ok) {
+            this.publish({ ...this.view, accessError: IDENTITY_ACCESS_FAILURE_MESSAGE });
+            return result;
+        }
+        this.publish({ ...this.view, recoveryProgress: result.value, accessError: null });
+        if (result.value.phase === 'applied')
+            clearRecoveryOtpRetryAt(operationId, this.config?.tenantId);
+        return result;
     }
     async resumeRecovery() {
         const progress = this.view.recoveryProgress;
@@ -980,6 +1196,7 @@ export class AwikiController {
             return this.recoveryLeft();
         if (!result.ok)
             return result;
+        clearRecoveryOtpRetryAt(progress.operationId, this.config?.tenantId);
         this.leaveRecovery();
         const opened = await this.open();
         return opened.ok ? result : opened;
@@ -999,10 +1216,23 @@ export class AwikiController {
             return this.recoveryLeft();
         if (!result.ok)
             return result;
+        clearRecoveryOtpRetryAt(operationId, this.config?.tenantId);
         this.leaveRecovery();
         void this.refreshIdentityAccess();
         return { ok: true, value: undefined };
     }
+    /** Return cached browser-safe runtime policy, or load it once on demand. */
+    async getConfig() {
+        if (this.config !== null)
+            return { ok: true, value: this.config };
+        const generation = this.generation;
+        const result = await call(() => this.remote.getConfig(), mailFailureMessage);
+        if (!this.current(generation))
+            return { ok: false, error: 'AWiki 会话已切换' };
+        if (result.ok)
+            this.config = result.value;
+        return result;
+    }
     /** Read the active deployment identity's public mailbox state. */
     getMailAccount() {
         return call(() => this.remote.getMailAccount(), mailFailureMessage);
@@ -1023,6 +1253,16 @@ export class AwikiController {
     sendMail(request) {
         return call(() => this.remote.sendMail(request), mailFailureMessage);
     }
+    /** Download one explicitly selected mail attachment without retaining its bytes. */
+    async downloadMailAttachment(request) {
+        if (this.disposed)
+            return { ok: false, error: 'AWiki 插件已卸载' };
+        const generation = this.generation;
+        const result = await call(() => this.remote.downloadMailAttachment(request), mailFailureMessage);
+        if (!this.current(generation))
+            return { ok: false, error: 'AWiki 已关闭' };
+        return result;
+    }
     /**
      * Load another page of the conversation roster.
      * @returns successful pagination or one display-safe failure.
@@ -1132,10 +1372,15 @@ export class AwikiController {
             return this.selectConversation(existing.id);
         }
         const generation = this.generation;
-        const resolved = await this.withPending('查找用户', () => call(() => this.remote.resolvePeer({ peer })));
-        if (!resolved.ok) {
-            return resolved.error.startsWith('not-found') ? this.fail('该 Handle 不存在') : resolved;
-        }
+        const resolved = await this.withPending('查找用户', async () => {
+            const result = await callWithFailureCode(() => this.remote.resolvePeer({ peer }));
+            if (!result.ok) {
+                return { ok: false, error: result.failureCode === 'not-found' ? '该 Handle 不存在' : result.error };
+            }
+            return result;
+        });
+        if (!resolved.ok)
+            return resolved;
         if (!this.current(generation))
             return { ok: true, value: undefined };
         if (resolved.value.did === identity.did)
@@ -1811,18 +2056,22 @@ export class AwikiController {
             }
             catch { }
         }
-        storeRecoveryOperation(null, tenantId);
+        clearRecoveryOtpRetryAt(this.view.recoveryOperationId, tenantId);
+        this.rememberRecoveryOperation(null, tenantId);
         if (!this.current(generation))
             return result;
         this.drafts.clearScope();
         this.close();
-        this.config = null;
+        // Preserve tenantId for the confirm-time getConfig scope check without reopening.
         this.conversationsCursor = undefined;
         this.historyCursor = undefined;
         this.unreadAtOpen.clear();
         this.summaryBaselines.clear();
         this.clearPresentationCache();
-        this.publish({ ...INITIAL_VIEW, status: 'ready', accessLoading: false, identityAccess: { choice: null, joining: false, recoveries: [] } });
+        this.publish({ ...INITIAL_VIEW, status: 'ready', accessLoading: false,
+            attachmentMaxBytes: this.config?.attachmentMaxBytes ?? INITIAL_VIEW.attachmentMaxBytes,
+            handleRecoveryPhoneEnabled: this.config?.handleRecoveryPhoneEnabled ?? false,
+            identityAccess: { choice: null, joining: false, recoveries: [] } });
         return result;
     }
     /** Read the Integration without coupling Guest Gateway health to the main AWiki view. */