botmux 3.4.3 → 3.5.0

package/dist/dashboard/bot-onboarding.js

@@ -1,18 +1,96 @@
 import { createRequire } from 'node:module';
-import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { readBotsJsonOrEmpty, writeBotsJsonAtomic } from '../setup/bots-store.js';
 import { atomicWriteFileSync } from '../utils/atomic-write.js';
 import { logger } from '../utils/logger.js';
 import { normalizeBotConfig, findInvalidAllowedUserEntries, hasOwnerEntry } from '../setup/bot-config-editor.js';
 import { tryRegisterApp } from '../setup/register-app.js';
-import { validateCredentials, buildRemainingSteps } from '../setup/verify-permissions.js';
+import { validateCredentials, readCriticalScopesFromApplicationInfo, buildRemainingSteps, } from '../setup/verify-permissions.js';
 import { resolveSetupAppName } from '../setup/app-name.js';
-import { automateOpenPlatformSetup, createFeishuOpenPlatformApp, inspectCachedFeishuOpenPlatformSession, } from '../setup/open-platform-automation.js';
+import { automateOpenPlatformSetup, BOT_BASELINE_APP_EVENTS, BOT_BASELINE_CALLBACKS, createFeishuOpenPlatformApp, inspectCachedFeishuOpenPlatformSession, } from '../setup/open-platform-automation.js';
 import { sdkDomain } from '../im/lark/lark-hosts.js';
 import * as Lark from '@larksuiteoapi/node-sdk';
 const require = createRequire(import.meta.url);
 const QRCode = require('qrcode-terminal/vendor/QRCode');
 const QRErrorCorrectLevel = require('qrcode-terminal/vendor/QRCode/QRErrorCorrectLevel');
+const MANAGED_VERIFIED_EVENT_COUNT = BOT_BASELINE_APP_EVENTS.length + BOT_BASELINE_CALLBACKS.length;
+function hasExactManagedAutomationAck(result) {
+    return result.ok
+        && result.eventMode === 4
+        && result.verifiedEventCount === MANAGED_VERIFIED_EVENT_COUNT
+        && typeof result.versionId === 'string'
+        && result.versionId.trim().length > 0;
+}
+function hasExactManagedPermissionAck(permission) {
+    return permission?.eventMode === 4
+        && permission.verifiedEventCount === MANAGED_VERIFIED_EVENT_COUNT
+        && typeof permission.versionId === 'string'
+        && permission.versionId.trim().length > 0;
+}
+function managedActivationStateForSnapshot(job) {
+    if (job.criticalScopeActivationRequired !== true
+        || !job.appId
+        || !job.workingDir
+        || job.platformQrScanConfirmedAt === undefined
+        || !hasExactManagedPermissionAck(job.permission)) {
+        return undefined;
+    }
+    if (job.status === 'failed'
+        && job.recoveryOfJobId
+        && job.error === 'permission_recovery_failed'
+        && job.permission?.ok === false
+        && job.permission.reason === 'scope_mapping_failed') {
+        return 'scope_propagation_pending';
+    }
+    if (job.status === 'completed'
+        && job.permission?.ok === true
+        && job.activationPending === true
+        && job.activationCommitting === true) {
+        return 'activation_committing';
+    }
+    if (job.status === 'completed'
+        && job.permission?.ok === true
+        && job.activationPending === true) {
+        return 'initial_scope_propagation_pending';
+    }
+    if (job.status === 'completed'
+        && job.permission?.ok === true
+        && job.activationPending !== true
+        && job.liveStarted === true) {
+        return 'completed';
+    }
+    return undefined;
+}
+function isExactManagedActivationMarker(value, appId, jobId) {
+    return !!value
+        && typeof value === 'object'
+        && !Array.isArray(value)
+        && value.appId === appId
+        && typeof value.jobId === 'string'
+        && (jobId === undefined || value.jobId === jobId);
+}
+function managedActivationMarker(bot) {
+    if (!bot || typeof bot !== 'object' || Array.isArray(bot))
+        return undefined;
+    const record = bot;
+    const appId = typeof record.larkAppId === 'string' ? record.larkAppId : '';
+    const markers = [
+        ['deactivating', record.activationDeactivating],
+        ['starting', record.activationStarting],
+        ['committed', record.activationCommitted],
+    ].filter(([, value]) => value !== undefined);
+    if (markers.length !== 1)
+        return undefined;
+    const [phase, value] = markers[0];
+    if (!isExactManagedActivationMarker(value, appId))
+        return undefined;
+    return {
+        phase,
+        appId,
+        jobId: value.jobId,
+    };
+}
 function svgEscape(value) {
     return value.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
 }
@@ -52,10 +130,19 @@ export class BotOnboardingManager {
     registerApp;
     validateCredentials;
     automateOpenPlatform;
+    verifyCriticalScopes;
+    criticalScopeStableReads;
+    criticalScopeMaxAttempts;
+    criticalScopePollIntervalMs;
     renderQrDataUrl;
     now;
     startBotLive;
     pendingStorePath;
+    stopBotLive;
+    permissionRecoveryStorePath;
+    scopePropagationFlights = new Map();
+    activationStartupReconciliation = Promise.resolve();
+    permissionRecoveryStateError;
     constructor(opts) {
         this.opts = opts;
         // 生产默认走单次 Web session；旧单测/外部注入若只给 registerApp，则明确
@@ -65,11 +152,33 @@ export class BotOnboardingManager {
         this.registerApp = opts.registerApp ?? tryRegisterApp;
         this.validateCredentials = opts.validateCredentials ?? validateCredentials;
         this.automateOpenPlatform = opts.automateOpenPlatform ?? automateOpenPlatformSetup;
+        this.verifyCriticalScopes = opts.verifyCriticalScopes ?? readCriticalScopesFromApplicationInfo;
+        this.criticalScopeStableReads = Number.isInteger(opts.criticalScopeStableReads)
+            && (opts.criticalScopeStableReads ?? 0) > 0
+            ? opts.criticalScopeStableReads
+            : 3;
+        const configuredMaxAttempts = Number.isInteger(opts.criticalScopeMaxAttempts)
+            && (opts.criticalScopeMaxAttempts ?? 0) > 0
+            ? opts.criticalScopeMaxAttempts
+            : 12;
+        this.criticalScopeMaxAttempts = Math.max(this.criticalScopeStableReads, configuredMaxAttempts);
+        this.criticalScopePollIntervalMs = Number.isInteger(opts.criticalScopePollIntervalMs)
+            && (opts.criticalScopePollIntervalMs ?? -1) >= 0
+            ? opts.criticalScopePollIntervalMs
+            : 5_000;
         this.renderQrDataUrl = opts.renderQrDataUrl ?? renderQrSvgDataUrl;
         this.now = opts.now ?? (() => Date.now());
         this.startBotLive = opts.startBotLive;
         this.pendingStorePath = opts.pendingStorePath ?? `${opts.botsJsonPath}.onboarding-pending.json`;
+        this.stopBotLive = opts.stopBotLive;
+        this.permissionRecoveryStorePath = opts.permissionRecoveryStorePath ?? `${opts.botsJsonPath}.permission-recoveries.json`;
         this.restorePendingJobs();
+        this.restorePermissionRecoveryJobs();
+        this.requireDurableManagedInitialJobs();
+        // A dashboard crash after PM2 has accepted the start but before the
+        // durable marker is cleared must converge to pending, never assume the
+        // daemon is safe to keep online.
+        this.activationStartupReconciliation = this.reconcileInterruptedManagedActivations();
     }
     /**
      * 恢复 owner 待确认任务。凭证只存在 0600 私有文件和内存中，公开 job snapshot
@@ -137,21 +246,640 @@ export class BotOnboardingManager {
             logger.warn(`[bot-onboarding] 无法持久化 owner 待确认任务: ${err?.message ?? String(err)}`);
         }
     }
+    restorePermissionRecoveryJobs() {
+        if (!existsSync(this.permissionRecoveryStorePath))
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.permissionRecoveryStorePath, 'utf8'));
+        }
+        catch (err) {
+            this.permissionRecoveryStateError = `permission recovery ledger is unreadable: ${err instanceof Error ? err.message : String(err)}`;
+            return;
+        }
+        if (parsed?.version !== 1 || !Array.isArray(parsed.jobs) || parsed.jobs.length > 128) {
+            this.permissionRecoveryStateError = 'permission recovery ledger schema is invalid';
+            return;
+        }
+        const records = parsed.jobs;
+        const restored = [];
+        const ids = new Set();
+        for (const raw of records) {
+            const isRecovery = (typeof raw?.recoveryOfJobId === 'string'
+                && raw.recoveryOfJobId.length > 0);
+            const isManagedInitial = (!isRecovery
+                && ['initial_scope_propagation_pending', 'activation_committing', 'completed'].includes(raw?.managedActivationState));
+            if (!raw || typeof raw !== 'object'
+                || typeof raw.id !== 'string'
+                || (isRecovery
+                    ? !/^botperm_[A-Za-z0-9_-]{1,160}$/.test(raw.id)
+                    : !/^bot_[A-Za-z0-9_-]{1,160}$/.test(raw.id))
+                || (!isRecovery && !isManagedInitial)
+                || ids.has(raw.id)
+                || typeof raw.appId !== 'string' || !raw.appId
+                || typeof raw.workingDir !== 'string' || !raw.workingDir
+                || !Number.isFinite(raw.createdAt) || !Number.isFinite(raw.updatedAt)
+                || (isRecovery
+                    ? (!Number.isInteger(raw.recoveryAttempt) || raw.recoveryAttempt < 1)
+                    : raw.recoveryAttempt !== undefined)
+                || !['starting', 'configuring_permissions', 'waiting_for_platform_scan', 'completed', 'failed'].includes(raw.status)
+                || (isManagedInitial && raw.status !== 'completed')
+                || !['feishu', 'lark'].includes(raw.brand)
+                || (raw.previousRecoveryJobId !== undefined
+                    && (!isRecovery || typeof raw.previousRecoveryJobId !== 'string'))
+                || (raw.platformQrScanConfirmedAt !== undefined
+                    && (!Number.isInteger(raw.platformQrScanConfirmedAt) || raw.platformQrScanConfirmedAt <= 0))
+                || (raw.activationDeactivating !== undefined && raw.activationDeactivating !== true)
+                || (raw.activationCommitting !== undefined && raw.activationCommitting !== true)) {
+                this.permissionRecoveryStateError = 'permission recovery ledger contains an invalid record';
+                return;
+            }
+            ids.add(raw.id);
+            const status = ['completed', 'failed'].includes(raw.status)
+                ? raw.status
+                : 'failed';
+            const snapshot = {
+                id: raw.id,
+                status,
+                createdAt: raw.createdAt,
+                updatedAt: this.now(),
+                appId: raw.appId,
+                brand: raw.brand === 'lark' ? 'lark' : 'feishu',
+                cliId: 'traex',
+                workingDir: raw.workingDir,
+                registrationMode: 'compat',
+                ...(isRecovery
+                    ? {
+                        recoveryOfJobId: raw.recoveryOfJobId,
+                        recoveryAttempt: raw.recoveryAttempt,
+                        ...(typeof raw.previousRecoveryJobId === 'string'
+                            ? { previousRecoveryJobId: raw.previousRecoveryJobId }
+                            : {}),
+                    }
+                    : {}),
+                ...(raw.criticalScopeActivationRequired === true
+                    ? { criticalScopeActivationRequired: true }
+                    : {}),
+                ...(raw.activationPending === true
+                    || raw.managedActivationState === 'initial_scope_propagation_pending'
+                    ? { activationPending: true }
+                    : {}),
+                ...(raw.activationDeactivating === true
+                    ? { activationDeactivating: true, activationPending: true }
+                    : {}),
+                ...(raw.activationCommitting === true
+                    ? { activationCommitting: true, activationPending: true }
+                    : {}),
+                ...(Number.isInteger(raw.platformQrScanConfirmedAt)
+                    ? { platformQrScanConfirmedAt: raw.platformQrScanConfirmedAt }
+                    : {}),
+                ...(raw.managedActivationState === 'initial_scope_propagation_pending'
+                    ? {
+                        permission: {
+                            ok: true,
+                            eventMode: raw.managedActivationAck?.eventMode,
+                            verifiedEventCount: raw.managedActivationAck?.verifiedEventCount,
+                            versionId: raw.managedActivationAck?.versionId,
+                        },
+                    }
+                    : {}),
+                ...(raw.managedActivationState === 'scope_propagation_pending'
+                    ? {
+                        permission: {
+                            ok: false,
+                            reason: 'scope_mapping_failed',
+                            message: '关键权限发布后仍在传播，等待 botmux 精确回读并启动',
+                            eventMode: raw.managedActivationAck?.eventMode,
+                            verifiedEventCount: raw.managedActivationAck?.verifiedEventCount,
+                            versionId: raw.managedActivationAck?.versionId,
+                        },
+                    }
+                    : {}),
+                ...(raw.managedActivationState === 'activation_committing'
+                    ? {
+                        activationPending: true,
+                        activationCommitting: true,
+                        permission: {
+                            ok: true,
+                            eventMode: raw.managedActivationAck?.eventMode,
+                            verifiedEventCount: raw.managedActivationAck?.verifiedEventCount,
+                            versionId: raw.managedActivationAck?.versionId,
+                        },
+                    }
+                    : {}),
+                ...(raw.managedActivationState === 'completed'
+                    ? {
+                        liveStarted: true,
+                        activationPending: false,
+                        permission: {
+                            ok: true,
+                            eventMode: raw.managedActivationAck?.eventMode,
+                            verifiedEventCount: raw.managedActivationAck?.verifiedEventCount,
+                            versionId: raw.managedActivationAck?.versionId,
+                        },
+                    }
+                    : {}),
+                ...(status === 'failed'
+                    ? {
+                        error: raw.status === 'failed' && typeof raw.error === 'string'
+                            ? raw.error
+                            : 'permission_recovery_interrupted',
+                        message: raw.status === 'failed' && typeof raw.message === 'string'
+                            ? raw.message
+                            : 'Dashboard restarted before permission recovery reached a terminal result',
+                    }
+                    : {}),
+            };
+            if ((raw.managedActivationState !== undefined
+                && ![
+                    'initial_scope_propagation_pending',
+                    'scope_propagation_pending',
+                    'activation_committing',
+                    'completed',
+                ].includes(raw.managedActivationState))
+                || (raw.managedActivationState === 'initial_scope_propagation_pending'
+                    && (raw.status !== 'completed'
+                        || raw.activationPending !== true))
+                || (raw.managedActivationState === 'scope_propagation_pending'
+                    && (!isRecovery
+                        || raw.status !== 'failed'
+                        || raw.error !== 'permission_recovery_failed'))
+                || (raw.managedActivationState === 'activation_committing'
+                    && (raw.status !== 'completed'
+                        || raw.activationPending !== true
+                        || raw.activationDeactivating === true
+                        || raw.activationCommitting !== true))
+                || (raw.managedActivationState === 'completed'
+                    && raw.status !== 'completed')
+                || ((raw.managedActivationState !== undefined)
+                    !== (raw.criticalScopeActivationRequired === true
+                        && Number.isInteger(raw.platformQrScanConfirmedAt)
+                        && raw.managedActivationAck?.eventMode === 4
+                        && raw.managedActivationAck?.verifiedEventCount === MANAGED_VERIFIED_EVENT_COUNT
+                        && typeof raw.managedActivationAck?.versionId === 'string'
+                        && raw.managedActivationAck.versionId.trim().length > 0))) {
+                this.permissionRecoveryStateError = 'permission recovery ledger contains an invalid activation ACK';
+                return;
+            }
+            restored.push(snapshot);
+        }
+        const groups = new Map();
+        for (const snapshot of restored.filter(item => item.recoveryOfJobId)) {
+            const key = JSON.stringify([snapshot.recoveryOfJobId, snapshot.workingDir, snapshot.appId]);
+            const group = groups.get(key) ?? [];
+            group.push(snapshot);
+            groups.set(key, group);
+        }
+        for (const group of groups.values()) {
+            group.sort((a, b) => (a.recoveryAttempt ?? 0) - (b.recoveryAttempt ?? 0));
+            for (let index = 0; index < group.length; index += 1) {
+                if (group[index].recoveryAttempt !== index + 1
+                    || (index === 0 && group[index].previousRecoveryJobId !== undefined)
+                    || (index > 0 && group[index].previousRecoveryJobId !== group[index - 1].id)) {
+                    this.permissionRecoveryStateError = 'permission recovery ledger lineage is ambiguous';
+                    return;
+                }
+            }
+        }
+        try {
+            for (const snapshot of restored) {
+                if (snapshot.error === 'permission_recovery_interrupted') {
+                    rmSync(join(dirname(this.opts.botsJsonPath), 'onboarding-sessions', `${snapshot.id}.json`), { force: true });
+                }
+            }
+        }
+        catch (err) {
+            this.permissionRecoveryStateError = `interrupted owner session could not be cleaned: ${err instanceof Error ? err.message : String(err)}`;
+            return;
+        }
+        for (const snapshot of restored) {
+            this.jobs.set(snapshot.id, snapshot);
+        }
+        try {
+            this.persistPermissionRecoveryJobs();
+        }
+        catch (err) {
+            this.permissionRecoveryStateError = `permission recovery ledger cannot be updated: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    persistPermissionRecoveryJobs() {
+        const jobs = [...this.jobs.values()]
+            .filter(job => ((job.recoveryOfJobId && job.appId && job.workingDir && job.recoveryAttempt)
+            || managedActivationStateForSnapshot(job) !== undefined))
+            .sort((a, b) => a.updatedAt - b.updatedAt)
+            .slice(-128)
+            .map(job => {
+            const managedActivationState = managedActivationStateForSnapshot(job);
+            return {
+                id: job.id,
+                status: job.status,
+                createdAt: job.createdAt,
+                updatedAt: job.updatedAt,
+                appId: job.appId,
+                brand: job.brand,
+                workingDir: job.workingDir,
+                recoveryOfJobId: job.recoveryOfJobId,
+                recoveryAttempt: job.recoveryAttempt,
+                previousRecoveryJobId: job.previousRecoveryJobId,
+                criticalScopeActivationRequired: job.criticalScopeActivationRequired,
+                activationPending: job.activationPending,
+                ...(job.activationDeactivating === true
+                    ? { activationDeactivating: true }
+                    : {}),
+                ...(job.activationCommitting === true
+                    ? { activationCommitting: true }
+                    : {}),
+                platformQrScanConfirmedAt: job.platformQrScanConfirmedAt,
+                error: job.error,
+                message: job.message,
+                ...(managedActivationState && hasExactManagedPermissionAck(job.permission)
+                    ? {
+                        managedActivationState,
+                        managedActivationAck: {
+                            eventMode: job.permission.eventMode,
+                            verifiedEventCount: job.permission.verifiedEventCount,
+                            versionId: job.permission.versionId,
+                        },
+                    }
+                    : {}),
+            };
+        });
+        if (jobs.length === 0)
+            return;
+        atomicWriteFileSync(this.permissionRecoveryStorePath, `${JSON.stringify({ version: 1, jobs }, null, 2)}\n`, { mode: 0o600 });
+    }
+    savePermissionRecoveryJobsBestEffort() {
+        try {
+            this.persistPermissionRecoveryJobs();
+        }
+        catch (err) {
+            logger.warn(`[bot-onboarding] 无法更新权限恢复 lineage: ${err?.message ?? String(err)}`);
+        }
+    }
+    /**
+     * A managed initial ACK is restart authority, not optional UI history.
+     * Refuse activation when its first durable write cannot be proven.
+     */
+    requireDurableManagedInitialJobs() {
+        if (this.permissionRecoveryStateError)
+            return;
+        const hasPendingInitial = [...this.jobs.values()].some(job => (!job.recoveryOfJobId
+            && managedActivationStateForSnapshot(job) === 'initial_scope_propagation_pending'));
+        if (!hasPendingInitial)
+            return;
+        try {
+            this.persistPermissionRecoveryJobs();
+        }
+        catch (err) {
+            this.permissionRecoveryStateError = `managed initial activation ledger could not be persisted: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
     /**
      * Best-effort auto-start of the just-persisted bot's daemon (no fleet restart).
      * Records the outcome on the job snapshot so the frontend shows "已自动上线"
      * instead of the restart hint. Never throws.
      */
-    async runLiveStart(id, appId) {
+    async runLiveStart(id, appId, recordOutcome = true) {
         if (!this.startBotLive)
-            return;
+            return { attempted: false };
         try {
             const r = await this.startBotLive(appId);
-            this.patch(id, { liveStarted: r.ok, liveStartMessage: r.message });
+            if (recordOutcome) {
+                this.patch(id, { liveStarted: r.ok, liveStartMessage: r.message });
+            }
+            return { attempted: true, ok: r.ok, message: r.message };
         }
         catch (err) {
-            this.patch(id, { liveStarted: false, liveStartMessage: err instanceof Error ? err.message : String(err) });
+            const message = err instanceof Error ? err.message : String(err);
+            if (recordOutcome) {
+                this.patch(id, { liveStarted: false, liveStartMessage: message });
+            }
+            return { attempted: true, ok: false, message };
+        }
+    }
+    async runLiveStop(id, appId) {
+        if (!this.stopBotLive)
+            return { attempted: false };
+        try {
+            const r = await this.stopBotLive(appId);
+            this.patch(id, { liveStopped: r.ok, liveStopMessage: r.message });
+            return { attempted: true, ok: r.ok, message: r.message };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.patch(id, { liveStopped: false, liveStopMessage: message });
+            return { attempted: true, ok: false, message };
+        }
+    }
+    async stableCriticalScopeReadback(id, appId, appSecret, brand) {
+        let consecutiveComplete = 0;
+        let readback = {
+            ok: false,
+            error: 'network',
+            message: '尚未读取权限状态',
+        };
+        for (let attempt = 1; attempt <= this.criticalScopeMaxAttempts; attempt += 1) {
+            try {
+                readback = await this.verifyCriticalScopes(appId, appSecret, brand);
+            }
+            catch (err) {
+                readback = {
+                    ok: false,
+                    error: 'network',
+                    message: err instanceof Error ? err.message : String(err),
+                };
+            }
+            if (readback.ok && readback.missingCritical.length === 0) {
+                consecutiveComplete += 1;
+            }
+            else {
+                consecutiveComplete = 0;
+            }
+            this.patch(id, {
+                permissionStatusMsg: consecutiveComplete > 0
+                    ? `正在确认 9 项核心权限稳定生效（${consecutiveComplete}/${this.criticalScopeStableReads}）`
+                    : `正在等待 9 项核心权限生效（${attempt}/${this.criticalScopeMaxAttempts}）`,
+            });
+            if (consecutiveComplete >= this.criticalScopeStableReads) {
+                return { ready: true, readback };
+            }
+            if (attempt < this.criticalScopeMaxAttempts
+                && this.criticalScopePollIntervalMs > 0) {
+                await new Promise(resolve => {
+                    setTimeout(resolve, this.criticalScopePollIntervalMs);
+                });
+            }
+        }
+        return { ready: false, readback };
+    }
+    async activateRecoveredBot(id, appId, addedBotIndex, ensureLiveStart = false) {
+        const bots = readBotsJsonOrEmpty(this.opts.botsJsonPath);
+        const current = bots[addedBotIndex];
+        if (!current
+            || typeof current !== 'object'
+            || current.larkAppId !== appId
+            || current.activationStarting !== undefined
+            || current.activationCommitted !== undefined
+            || current.activationCommitting !== undefined) {
+            throw new Error('permission_recovery_activation_target_drift');
+        }
+        // Existing pre-gate bots were already daemon-visible. Their exact App may
+        // recover permissions without performing a second activation transition.
+        if (current.activationPending !== true && !ensureLiveStart) {
+            return;
+        }
+        this.beginManagedActivation(id, appId, addedBotIndex);
+        const live = await this.runLiveStart(id, appId, false);
+        if (live.attempted && live.ok === true) {
+            try {
+                this.patch(id, {
+                    activationPending: true,
+                    activationCommitting: true,
+                    liveStarted: false,
+                    liveStartMessage: live.message,
+                });
+                this.persistPermissionRecoveryJobs();
+                this.commitManagedActivation(id, appId, addedBotIndex);
+                this.completeManagedActivation(id, appId, addedBotIndex);
+                return;
+            }
+            catch (err) {
+                const stopped = await this.runLiveStop(id, appId);
+                if (stopped.attempted && stopped.ok === true) {
+                    this.restoreManagedActivationPending(id, appId, addedBotIndex);
+                }
+                throw err;
+            }
+        }
+        // An exit/timeout from start-bot is an unknown PM2 outcome. Stop and
+        // re-read the exact App before returning it to pending; otherwise a daemon
+        // could remain online while the durable config says it is blocked.
+        const stopped = await this.runLiveStop(id, appId);
+        if (!stopped.attempted || stopped.ok !== true) {
+            throw new Error(`permission_recovery_activation_stop_not_acknowledged${stopped.message ? `: ${stopped.message}` : ''}`);
+        }
+        this.restoreManagedActivationPending(id, appId, addedBotIndex);
+        throw new Error(`permission_recovery_activation_not_acknowledged${live.message ? `: ${live.message}` : ''}`);
+    }
+    beginManagedActivation(id, appId, addedBotIndex) {
+        const bots = readBotsJsonOrEmpty(this.opts.botsJsonPath);
+        const current = bots[addedBotIndex];
+        if (!current
+            || typeof current !== 'object'
+            || current.larkAppId !== appId
+            || current.activationPending !== true) {
+            throw new Error('permission_recovery_activation_target_drift');
+        }
+        const next = [...bots];
+        const activating = {
+            ...current,
+            activationStarting: { appId, jobId: id },
+        };
+        delete activating.activationPending;
+        delete activating.activationDeactivating;
+        delete activating.activationCommitting;
+        next[addedBotIndex] = activating;
+        writeBotsJsonAtomic(this.opts.botsJsonPath, next);
+    }
+    commitManagedActivation(id, appId, addedBotIndex) {
+        const bots = readBotsJsonOrEmpty(this.opts.botsJsonPath);
+        const current = bots[addedBotIndex];
+        if (!current
+            || typeof current !== 'object'
+            || current.larkAppId !== appId
+            || current.activationPending === true
+            || !isExactManagedActivationMarker(current.activationStarting, appId, id)) {
+            throw new Error('permission_recovery_activation_ack_target_drift');
+        }
+        const next = [...bots];
+        const ready = { ...current, activationCommitted: { appId, jobId: id } };
+        delete ready.activationStarting;
+        next[addedBotIndex] = ready;
+        writeBotsJsonAtomic(this.opts.botsJsonPath, next);
+    }
+    restoreManagedActivationPending(id, appId, addedBotIndex) {
+        const bots = readBotsJsonOrEmpty(this.opts.botsJsonPath);
+        const current = bots[addedBotIndex];
+        if (!current
+            || typeof current !== 'object'
+            || current.larkAppId !== appId
+            || (!isExactManagedActivationMarker(current.activationStarting, appId, id)
+                && !isExactManagedActivationMarker(current.activationDeactivating, appId, id)
+                && !isExactManagedActivationMarker(current.activationCommitted, appId, id))) {
+            throw new Error('permission_recovery_activation_rollback_target_drift');
+        }
+        const next = [...bots];
+        const pending = { ...current, activationPending: true };
+        delete pending.activationStarting;
+        delete pending.activationDeactivating;
+        delete pending.activationCommitted;
+        next[addedBotIndex] = pending;
+        writeBotsJsonAtomic(this.opts.botsJsonPath, next);
+        this.patch(id, {
+            activationPending: true,
+            activationDeactivating: false,
+            activationCommitting: false,
+            liveStarted: false,
+        });
+    }
+    completeManagedActivation(id, appId, addedBotIndex) {
+        const bots = readBotsJsonOrEmpty(this.opts.botsJsonPath);
+        const current = bots[addedBotIndex];
+        if (!current
+            || typeof current !== 'object'
+            || current.larkAppId !== appId
+            || current.activationPending === true
+            || current.activationStarting !== undefined
+            || current.activationDeactivating !== undefined
+            || !isExactManagedActivationMarker(current.activationCommitted, appId, id)) {
+            throw new Error('permission_recovery_activation_completion_target_drift');
+        }
+        this.patch(id, {
+            activationPending: false,
+            activationCommitting: false,
+            liveStarted: true,
+        });
+        this.persistPermissionRecoveryJobs();
+        const next = [...bots];
+        const ready = { ...current };
+        delete ready.activationCommitted;
+        next[addedBotIndex] = ready;
+        writeBotsJsonAtomic(this.opts.botsJsonPath, next);
+    }
+    clearManagedActivationCommitted(id, appId, addedBotIndex) {
+        const bots = readBotsJsonOrEmpty(this.opts.botsJsonPath);
+        const current = bots[addedBotIndex];
+        if (!current
+            || typeof current !== 'object'
+            || current.larkAppId !== appId
+            || !isExactManagedActivationMarker(current.activationCommitted, appId, id)) {
+            throw new Error('permission_recovery_activation_committed_target_drift');
+        }
+        const next = [...bots];
+        const ready = { ...current };
+        delete ready.activationCommitted;
+        next[addedBotIndex] = ready;
+        writeBotsJsonAtomic(this.opts.botsJsonPath, next);
+    }
+    async reconcileInterruptedManagedActivations() {
+        const targets = readBotsJsonOrEmpty(this.opts.botsJsonPath).flatMap((bot, index) => {
+            const marker = managedActivationMarker(bot);
+            if (!marker) {
+                if (bot
+                    && typeof bot === 'object'
+                    && (bot.activationDeactivating !== undefined
+                        || bot.activationStarting !== undefined
+                        || bot.activationCommitted !== undefined
+                        || bot.activationCommitting !== undefined)) {
+                    this.permissionRecoveryStateError = 'managed activation marker is invalid';
+                }
+                return [];
+            }
+            if (marker.phase === 'deactivating'
+                || marker.phase === 'starting'
+                || marker.phase === 'committed') {
+                return [{ index, ...marker }];
+            }
+            if (!marker.appId) {
+                this.permissionRecoveryStateError = 'managed activation marker is invalid';
+                return [];
+            }
+            return [];
+        });
+        if (this.permissionRecoveryStateError)
+            return;
+        for (const target of targets) {
+            try {
+                const job = this.jobs.get(target.jobId);
+                if (target.phase === 'committed'
+                    && job?.status === 'completed'
+                    && job.activationPending !== true
+                    && job.liveStarted === true) {
+                    this.clearManagedActivationCommitted(target.jobId, target.appId, target.index);
+                    continue;
+                }
+                const stopped = await this.runLiveStop(target.jobId, target.appId);
+                if (!stopped.attempted || stopped.ok !== true) {
+                    this.permissionRecoveryStateError = `managed activation stop could not be confirmed for ${target.appId}`;
+                    return;
+                }
+                this.restoreManagedActivationPending(target.jobId, target.appId, target.index);
+            }
+            catch (err) {
+                this.permissionRecoveryStateError = `managed activation rollback failed: ${err instanceof Error ? err.message : String(err)}`;
+                return;
+            }
+        }
+        for (const job of this.jobs.values()) {
+            if (job.activationCommitting !== true
+                || job.status !== 'completed'
+                || !job.appId
+                || !job.workingDir) {
+                continue;
+            }
+            const matches = readBotsJsonOrEmpty(this.opts.botsJsonPath).flatMap((bot, index) => (bot
+                && typeof bot === 'object'
+                && bot.larkAppId === job.appId
+                && bot.cliId === 'traex'
+                && bot.defaultWorkingDir === job.workingDir
+                && bot.activationPending !== true
+                && bot.activationStarting === undefined
+                && bot.activationDeactivating === undefined
+                && isExactManagedActivationMarker(bot.activationCommitted, job.appId, job.id)
+                ? [index]
+                : []));
+            if (matches.length !== 1) {
+                this.permissionRecoveryStateError = `managed activation commit could not be reconciled for ${job.appId}`;
+                return;
+            }
+            try {
+                this.completeManagedActivation(job.id, job.appId, matches[0]);
+            }
+            catch (err) {
+                this.permissionRecoveryStateError = `managed activation commit reconciliation failed: ${err instanceof Error ? err.message : String(err)}`;
+                return;
+            }
+        }
+    }
+    holdRecoveryActivation(id, appId, addedBotIndex) {
+        const bots = readBotsJsonOrEmpty(this.opts.botsJsonPath);
+        const current = bots[addedBotIndex];
+        if (!current
+            || typeof current !== 'object'
+            || current.larkAppId !== appId) {
+            throw new Error('permission_recovery_activation_target_drift');
+        }
+        if (current.activationStarting !== undefined
+            || current.activationCommitted !== undefined
+            || (current.activationDeactivating !== undefined
+                && !isExactManagedActivationMarker(current.activationDeactivating, appId, id))) {
+            throw new Error('permission_recovery_activation_target_drift');
+        }
+        const next = [...bots];
+        next[addedBotIndex] = {
+            ...current,
+            activationPending: true,
+            activationDeactivating: { appId, jobId: id },
+        };
+        writeBotsJsonAtomic(this.opts.botsJsonPath, next);
+        this.patch(id, { activationPending: true, activationDeactivating: true });
+        this.persistPermissionRecoveryJobs();
+    }
+    markManagedDeactivated(id, appId, addedBotIndex) {
+        const bots = readBotsJsonOrEmpty(this.opts.botsJsonPath);
+        const current = bots[addedBotIndex];
+        if (!current
+            || typeof current !== 'object'
+            || current.larkAppId !== appId
+            || !isExactManagedActivationMarker(current.activationDeactivating, appId, id)) {
+            throw new Error('permission_recovery_deactivation_target_drift');
         }
+        const next = [...bots];
+        const pending = { ...current, activationPending: true };
+        delete pending.activationDeactivating;
+        next[addedBotIndex] = pending;
+        writeBotsJsonAtomic(this.opts.botsJsonPath, next);
+        this.patch(id, { activationPending: true, activationDeactivating: false });
     }
     start(input = {}) {
         const id = `bot_${Math.random().toString(36).slice(2)}_${this.now().toString(36)}`;
@@ -166,6 +894,221 @@ export class BotOnboardingManager {
         });
         return { id, done };
     }
+    /**
+     * Resume only Open Platform authorization for one already-persisted Space
+     * Agent. The exact neutral working directory is the durable target anchor:
+     * zero or multiple matching bots fail closed, and this path never creates an
+     * App or registers another Bot. A managed caller may place the exact existing
+     * row behind the critical-scope activation marker before the fresh QR.
+     */
+    startPermissionRecovery(input) {
+        if (this.permissionRecoveryStateError) {
+            return { ok: false, error: 'permission_recovery_state_unavailable' };
+        }
+        const configuredBots = readBotsJsonOrEmpty(this.opts.botsJsonPath);
+        if (configuredBots.some((bot) => (bot?.activationDeactivating !== undefined
+            || bot?.activationStarting !== undefined
+            || bot?.activationCommitted !== undefined))) {
+            return { ok: false, error: 'permission_recovery_state_unavailable' };
+        }
+        const candidates = configuredBots.flatMap((bot, index) => {
+            if (!bot
+                || typeof bot !== 'object'
+                || bot.cliId !== 'traex'
+                || bot.defaultWorkingDir !== input.workingDir) {
+                return [];
+            }
+            const appId = typeof bot.larkAppId === 'string' ? bot.larkAppId.trim() : '';
+            const appSecret = typeof bot.larkAppSecret === 'string' ? bot.larkAppSecret : '';
+            if (!appId || !appSecret || !Array.isArray(bot.allowedUsers) || !hasOwnerEntry(bot.allowedUsers))
+                return [];
+            return [{ appId, appSecret, brand: bot.brand === 'lark' ? 'lark' : 'feishu', index }];
+        });
+        if (candidates.length === 0)
+            return { ok: false, error: 'permission_recovery_target_missing' };
+        if (candidates.length !== 1)
+            return { ok: false, error: 'permission_recovery_target_ambiguous' };
+        if (!input.predecessorJobId || !input.workingDir || !input.expectedAppId || candidates[0].appId !== input.expectedAppId) {
+            return { ok: false, error: 'permission_recovery_target_invalid' };
+        }
+        const lineage = [...this.jobs.values()].filter(job => job.recoveryOfJobId === input.predecessorJobId
+            && job.workingDir === input.workingDir
+            && job.appId === input.expectedAppId).sort((a, b) => (a.recoveryAttempt ?? 0) - (b.recoveryAttempt ?? 0));
+        const latest = lineage.at(-1);
+        if (!input.priorRecoveryJobId) {
+            if (latest)
+                return { ok: true, job: { id: latest.id, done: Promise.resolve() } };
+        }
+        else {
+            if (!latest || latest.id !== input.priorRecoveryJobId) {
+                return { ok: false, error: 'permission_recovery_target_invalid' };
+            }
+            if (!['completed', 'failed'].includes(latest.status)) {
+                return { ok: true, job: { id: latest.id, done: Promise.resolve() } };
+            }
+        }
+        const target = candidates[0];
+        const id = `botperm_${Math.random().toString(36).slice(2)}_${this.now().toString(36)}`;
+        const createdAt = this.now();
+        this.jobs.set(id, {
+            id,
+            status: 'starting',
+            createdAt,
+            updatedAt: createdAt,
+            appId: target.appId,
+            brand: target.brand,
+            cliId: 'traex',
+            workingDir: input.workingDir,
+            registrationMode: 'compat',
+            recoveryOfJobId: input.predecessorJobId,
+            recoveryAttempt: (latest?.recoveryAttempt ?? 0) + 1,
+            ...(input.requireCriticalScopesBeforeActivation === true
+                ? { criticalScopeActivationRequired: true }
+                : {}),
+            ...(latest ? { previousRecoveryJobId: latest.id } : {}),
+        });
+        try {
+            this.persistPermissionRecoveryJobs();
+        }
+        catch {
+            this.jobs.delete(id);
+            this.permissionRecoveryStateError = 'permission recovery intent could not be persisted';
+            return { ok: false, error: 'permission_recovery_state_unavailable' };
+        }
+        const done = this.runPermissionRecovery(id, target.appId, target.appSecret, target.brand, target.index, input.requireCriticalScopesBeforeActivation === true).catch(err => {
+            this.patch(id, {
+                status: 'failed',
+                error: 'permission_recovery_failed',
+                message: err instanceof Error ? err.message : String(err),
+            });
+        });
+        return { ok: true, job: { id, done } };
+    }
+    /**
+     * Finish only the exact activation-pending tail of an already-scanned
+     * managed initial/recovery job. This never opens SSO, creates an App, or
+     * issues another owner QR. botmux itself re-reads stable scopes, removes
+     * activationPending, and requires an idempotent exact-daemon start ACK
+     * before returning success.
+     */
+    async completeScopePropagation(input) {
+        await this.activationStartupReconciliation;
+        if (this.permissionRecoveryStateError) {
+            return { ok: false, error: 'permission_recovery_state_unavailable' };
+        }
+        const job = this.jobs.get(input.jobId);
+        if (!job)
+            return { ok: false, error: 'permission_recovery_target_missing' };
+        const exactTarget = (job.workingDir === input.workingDir
+            && job.appId === input.expectedAppId
+            && job.criticalScopeActivationRequired === true);
+        if (!exactTarget) {
+            return { ok: false, error: 'permission_recovery_target_invalid' };
+        }
+        if (job.status === 'completed'
+            && job.activationPending !== true
+            && job.liveStarted === true
+            && job.permission?.ok === true
+            && job.permission.eventMode === 4
+            && job.permission.verifiedEventCount === MANAGED_VERIFIED_EVENT_COUNT
+            && typeof job.permission.versionId === 'string'
+            && job.permission.versionId.trim().length > 0) {
+            return { ok: true };
+        }
+        const exactAck = (job.permission?.eventMode === 4
+            && job.permission.verifiedEventCount === MANAGED_VERIFIED_EVENT_COUNT
+            && typeof job.permission.versionId === 'string'
+            && job.permission.versionId.trim().length > 0);
+        const initialPropagationPending = (job.status === 'completed'
+            && job.activationPending === true
+            && job.liveStarted !== true
+            && job.permission?.ok === true
+            && job.activationCommitting !== true);
+        const recoveryPropagationPending = (job.status === 'failed'
+            && job.error === 'permission_recovery_failed'
+            && job.permission?.ok === false
+            && job.permission.reason === 'scope_mapping_failed');
+        if (job.platformQrScanConfirmedAt === undefined
+            || !exactAck
+            || (!initialPropagationPending && !recoveryPropagationPending)) {
+            return { ok: false, error: 'permission_recovery_target_invalid' };
+        }
+        const existingFlight = this.scopePropagationFlights.get(job.id);
+        if (existingFlight)
+            return existingFlight;
+        const flight = this.finishScopePropagation(job, input);
+        this.scopePropagationFlights.set(job.id, flight);
+        try {
+            return await flight;
+        }
+        finally {
+            if (this.scopePropagationFlights.get(job.id) === flight) {
+                this.scopePropagationFlights.delete(job.id);
+            }
+        }
+    }
+    async finishScopePropagation(job, input) {
+        const managedPermission = job.permission;
+        if (!managedPermission) {
+            return { ok: false, error: 'permission_recovery_target_invalid' };
+        }
+        const candidates = readBotsJsonOrEmpty(this.opts.botsJsonPath).flatMap((bot, index) => {
+            if (!bot
+                || typeof bot !== 'object'
+                || bot.cliId !== 'traex'
+                || bot.defaultWorkingDir !== input.workingDir
+                || bot.larkAppId !== input.expectedAppId
+                || typeof bot.larkAppSecret !== 'string'
+                || !bot.larkAppSecret
+                || !Array.isArray(bot.allowedUsers)
+                || !hasOwnerEntry(bot.allowedUsers)) {
+                return [];
+            }
+            return [{
+                    index,
+                    appSecret: bot.larkAppSecret,
+                    brand: bot.brand === 'lark' ? 'lark' : 'feishu',
+                }];
+        });
+        if (candidates.length === 0) {
+            return { ok: false, error: 'permission_recovery_target_missing' };
+        }
+        if (candidates.length !== 1) {
+            return { ok: false, error: 'permission_recovery_target_ambiguous' };
+        }
+        const target = candidates[0];
+        const stable = await this.stableCriticalScopeReadback(job.id, input.expectedAppId, target.appSecret, target.brand);
+        if (!stable.ready) {
+            return { ok: false, error: 'permission_recovery_scopes_pending' };
+        }
+        const permissionAck = {
+            ok: true,
+            sessionFile: 'permission-recovery-ledger',
+            sessionSource: 'qr_login',
+            cookieCount: 0,
+            scopeCount: 9,
+            skippedScopeCount: 0,
+            subscribedEventCount: MANAGED_VERIFIED_EVENT_COUNT,
+            missingVcEvents: [],
+            eventModeReady: true,
+            eventMode: managedPermission.eventMode,
+            verifiedEventCount: managedPermission.verifiedEventCount,
+            versionId: managedPermission.versionId,
+        };
+        this.finalizePermissions(job.id, input.expectedAppId, target.brand, target.index, permissionAck, 'completed');
+        try {
+            await this.activateRecoveredBot(job.id, input.expectedAppId, target.index, true);
+        }
+        catch {
+            return { ok: false, error: 'permission_recovery_activation_failed' };
+        }
+        this.patch(job.id, {
+            error: undefined,
+            message: undefined,
+            remainingSteps: undefined,
+        });
+        return { ok: true };
+    }
     get(id) {
         const job = this.jobs.get(id);
         return job ? { ...job } : undefined;
@@ -183,7 +1126,23 @@ export class BotOnboardingManager {
         const current = this.jobs.get(id);
         if (!current)
             return;
-        this.jobs.set(id, { ...current, ...patch, updatedAt: this.now() });
+        const next = { ...current, ...patch, updatedAt: this.now() };
+        this.jobs.set(id, next);
+        if (current.recoveryOfJobId
+            || next.recoveryOfJobId
+            || managedActivationStateForSnapshot(current) !== undefined
+            || managedActivationStateForSnapshot(next) !== undefined) {
+            this.savePermissionRecoveryJobsBestEffort();
+        }
+    }
+    confirmPlatformQrScan(id, confirmedAt) {
+        const current = this.jobs.get(id);
+        if (!current || current.platformQrScanConfirmedAt !== undefined)
+            return;
+        if (!Number.isInteger(confirmedAt) || confirmedAt <= 0) {
+            throw new Error('platform_qr_scan_confirmation_invalid');
+        }
+        this.patch(id, { platformQrScanConfirmedAt: confirmedAt });
     }
     async run(id, input = {}) {
         // Freeze the resolved name before any asynchronous work. Later bot list
@@ -191,6 +1150,9 @@ export class BotOnboardingManager {
         const appName = resolveSetupAppName(input.appName, readBotsJsonOrEmpty(this.opts.botsJsonPath).length);
         this.patch(id, {
             registrationMode: input.registrationMode ?? 'web',
+            ...(input.requireCriticalScopesBeforeActivation
+                ? { criticalScopeActivationRequired: true }
+                : {}),
             // SDK/Lark compatibility mode cannot apply a custom application name, so
             // do not claim that the resolved Feishu name was used.
             ...(input.registrationMode === 'compat' ? {} : { appName }),
@@ -291,7 +1253,18 @@ export class BotOnboardingManager {
             cliId,
             workingDir,
             registrationMode: input.registrationMode ?? 'web',
+            requireVerifiedEvents: input.requireCriticalScopesBeforeActivation === true,
         });
+        // Every managed initial App first reaches one durable activation-pending
+        // snapshot. Even when scopes are immediately stable, starting here would
+        // leave a crash window between the exact PM2 ACK and persistence of the
+        // owner-session event/version ACK. The Web helper always completes this
+        // same job through the singleflight scope-propagation endpoint.
+        const activationPending = input.requireCriticalScopesBeforeActivation === true;
+        if (activationPending) {
+            bot.activationPending = true;
+            this.patch(id, { activationPending: true });
+        }
         // 关键顺序：先确认 owner, 再决定是否落盘 + 终态。completed 必须意味着「bots.json
         // 里这个 bot 带着至少一个 owner」, 绝不产出空 allowedUsers 的可启动 bot。
         let ownerEntry;
@@ -310,7 +1283,9 @@ export class BotOnboardingManager {
         }
         if (ownerEntry) {
             const addedBotIndex = this.persistBot({ ...bot, allowedUsers: [ownerEntry] });
-            await this.runLiveStart(id, result.appId);
+            if (!activationPending) {
+                await this.runLiveStart(id, result.appId);
+            }
             this.finalizePermissions(id, result.appId, result.brand, addedBotIndex, auto, 'completed');
         }
         else {
@@ -392,8 +1367,14 @@ export class BotOnboardingManager {
         // 校验通过才落盘：此刻 bot 第一次进入 bots.json, 且带着非空 allowedUsers。
         const addedBotIndex = this.persistBot({ ...pending, allowedUsers: entries });
         this.pendingBots.delete(id);
-        await this.runLiveStart(id, appId);
+        if (pending.activationPending === true) {
+            this.patch(id, { activationPending: true });
+        }
+        else {
+            await this.runLiveStart(id, appId);
+        }
         this.patch(id, { status: 'completed', addedBotIndex });
+        this.requireDurableManagedInitialJobs();
         this.savePendingJobs();
         return { ok: true };
     }
@@ -409,8 +1390,27 @@ export class BotOnboardingManager {
             cliId: meta.cliId,
             workingDir: meta.workingDir,
         });
+        const callbacks = {
+            onQrCode: (info) => {
+                this.patch(id, {
+                    status: 'waiting_for_platform_scan',
+                    platformQrDataUrl: this.renderQrDataUrl(info.qrPayload),
+                });
+            },
+            onQrScanConfirmed: (info) => {
+                this.confirmPlatformQrScan(id, info.confirmedAt);
+            },
+            onStatus: (msg) => {
+                // onStatus follows onQrCode while polling; keep the QR visible.
+                this.patch(id, { permissionStatusMsg: msg });
+            },
+        };
         try {
-            return await this.automateOpenPlatform({
+            if (meta.registrationMode === 'compat') {
+                const sessionFilePath = join(dirname(this.opts.botsJsonPath), 'onboarding-sessions', `${id}.json`);
+                return await this.runOwnerPermissionAutomation(id, appId, brand, callbacks, sessionFilePath, meta.requireVerifiedEvents);
+            }
+            const first = await this.automateOpenPlatform({
                 appId,
                 brand,
                 // The Feishu primary path must never surprise the user with a second
@@ -418,19 +1418,10 @@ export class BotOnboardingManager {
                 // manual recovery. Only explicit compatibility mode may scan again.
                 disableQrLogin: meta.registrationMode === 'web',
                 disableBytedcliFallback: meta.registrationMode === 'web',
-                onQrCode: info => {
-                    this.patch(id, {
-                        status: 'waiting_for_platform_scan',
-                        platformQrDataUrl: this.renderQrDataUrl(info.qrPayload),
-                    });
-                },
-                onStatus: msg => {
-                    // 只更新进度文案, 不动 status——onStatus 在 onQrCode 之后的轮询里就会
-                    // 触发 ('等待飞书扫码'), 若把 status 拨回 configuring_permissions 会瞬间
-                    // 把刚弹出的第二个二维码 (waiting_for_platform_scan) 盖掉.
-                    this.patch(id, { permissionStatusMsg: msg });
-                },
+                requireVerifiedEvents: meta.requireVerifiedEvents,
+                ...callbacks,
             });
+            return first;
         }
         catch (err) {
             // automation 不应抛 (内部已结构化返回), 兜底当作失败 → 手动步骤.
@@ -441,11 +1432,88 @@ export class BotOnboardingManager {
             };
         }
     }
+    async runPermissionRecovery(id, appId, appSecret, brand, addedBotIndex, requireCriticalScopesBeforeActivation) {
+        if (requireCriticalScopesBeforeActivation) {
+            this.holdRecoveryActivation(id, appId, addedBotIndex);
+            const stopped = await this.runLiveStop(id, appId);
+            if (!stopped.attempted || stopped.ok !== true) {
+                throw new Error(`permission_recovery_deactivation_not_acknowledged${stopped.message ? `: ${stopped.message}` : ''}`);
+            }
+            this.markManagedDeactivated(id, appId, addedBotIndex);
+        }
+        this.patch(id, { status: 'configuring_permissions' });
+        const sessionFilePath = join(dirname(this.opts.botsJsonPath), 'onboarding-sessions', `${id}.json`);
+        const auto = await this.runOwnerPermissionAutomation(id, appId, brand, {
+            onQrCode: (info) => {
+                this.patch(id, {
+                    status: 'waiting_for_platform_scan',
+                    platformQrDataUrl: this.renderQrDataUrl(info.qrPayload),
+                });
+            },
+            onQrScanConfirmed: (info) => {
+                this.confirmPlatformQrScan(id, info.confirmedAt);
+            },
+            onStatus: (msg) => this.patch(id, { permissionStatusMsg: msg }),
+        }, sessionFilePath, requireCriticalScopesBeforeActivation);
+        if (!auto.ok) {
+            this.finalizePermissions(id, appId, brand, addedBotIndex, auto, 'failed', 'permission_recovery_failed');
+            return;
+        }
+        if (requireCriticalScopesBeforeActivation && !hasExactManagedAutomationAck(auto)) {
+            this.finalizePermissions(id, appId, brand, addedBotIndex, {
+                ok: false,
+                reason: 'event_verification_failed',
+                message: '受管权限恢复缺少同一 owner 会话的事件与版本精确 ACK',
+            }, 'failed', 'permission_recovery_failed');
+            return;
+        }
+        if (requireCriticalScopesBeforeActivation
+            && this.jobs.get(id)?.platformQrScanConfirmedAt === undefined) {
+            throw new Error('platform_qr_scan_not_confirmed');
+        }
+        const stableScopeReadback = await this.stableCriticalScopeReadback(id, appId, appSecret, brand);
+        const scopeReadback = stableScopeReadback.readback;
+        if (!stableScopeReadback.ready) {
+            const failed = {
+                ok: false,
+                reason: scopeReadback.ok ? 'scope_mapping_failed' : 'api_error',
+                message: scopeReadback.ok
+                    ? scopeReadback.missingCritical.length > 0
+                        ? `关键权限回读仍缺失: ${scopeReadback.missingCritical.map(scope => scope.name).join(', ')}`
+                        : `9 项核心权限尚未连续稳定生效（需要连续 ${this.criticalScopeStableReads} 次）`
+                    : `关键权限回读失败: ${scopeReadback.message}`,
+                eventMode: auto.eventMode,
+                verifiedEventCount: auto.verifiedEventCount,
+                versionId: auto.versionId,
+            };
+            this.finalizePermissions(id, appId, brand, addedBotIndex, failed, 'failed', 'permission_recovery_failed');
+            return;
+        }
+        this.finalizePermissions(id, appId, brand, addedBotIndex, auto, 'completed');
+        await this.activateRecoveredBot(id, appId, addedBotIndex);
+    }
+    async runOwnerPermissionAutomation(id, appId, brand, callbacks, sessionFilePath, requireVerifiedEvents) {
+        try {
+            return await this.automateOpenPlatform({
+                appId,
+                brand,
+                sessionFilePath,
+                forceQrLogin: true,
+                disableQrLogin: false,
+                disableBytedcliFallback: true,
+                requireVerifiedEvents,
+                ...callbacks,
+            });
+        }
+        finally {
+            rmSync(sessionFilePath, { force: true });
+        }
+    }
     /**
      * 统一落终态：completed (已落盘 + 有 owner) 或 needs_owner (尚未落盘、待用户手动填)。
      * needs_owner 时 addedBotIndex 为 undefined——bot 还没进 bots.json, 没有行号。
      */
-    finalizePermissions(id, appId, brand, addedBotIndex, auto, status) {
+    finalizePermissions(id, appId, brand, addedBotIndex, auto, status, error) {
         const permission = auto.ok
             ? {
                 ok: true,
@@ -453,15 +1521,26 @@ export class BotOnboardingManager {
                 skippedScopeCount: auto.skippedScopeCount,
                 versionId: auto.versionId,
                 scopeWarning: auto.scopeWarning,
+                eventMode: auto.eventMode,
+                verifiedEventCount: auto.verifiedEventCount,
             }
-            : { ok: false, reason: auto.reason, message: auto.message };
+            : {
+                ok: false,
+                reason: auto.reason,
+                message: auto.message,
+                eventMode: auto.eventMode,
+                verifiedEventCount: auto.verifiedEventCount,
+                versionId: auto.versionId,
+            };
         this.patch(id, {
             status,
             ...(addedBotIndex !== undefined ? { addedBotIndex } : {}),
             platformQrDataUrl: undefined,
             permission,
+            ...(error ? { error } : {}),
             ...(auto.ok ? {} : { remainingSteps: buildRemainingSteps(appId, brand) }),
         });
+        this.requireDurableManagedInitialJobs();
     }
 }
 /**