botmux 3.10.0 → 3.11.0

package/dist/core/dashboard-ipc-server.js

@@ -1,7 +1,7 @@
 // src/core/dashboard-ipc-server.ts
 import { createServer } from 'node:http';
 import { execFileSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { logger } from '../utils/logger.js';
 import { cliAuthBind, verifyHmac } from '../dashboard/auth.js';
@@ -9,6 +9,7 @@ import { WORKFLOW_DAEMON_IPC_ROUTE_PREFIX } from '../workflows/v3/daemon-ipc-aut
 import { V3_SESSION_RUN_MUTATION_ROUTE_PREFIX } from '../workflows/v3/session-relay.js';
 import { listenWithProbe } from '../utils/listen-with-probe.js';
 import { dashboardSecretPath } from './dashboard-secret.js';
+import { MANAGED_ORIGIN_ATTEST_ROUTE, MANAGED_ORIGIN_PROOF_DOMAIN, MANAGED_ORIGIN_PROOF_TTL_MS, writeManagedOriginAttestationProof, } from './managed-origin-attestation.js';
 import * as sessionStore from '../services/session-store.js';
 import { cliSupportsNativeUsage } from '../services/transcript-resolver.js';
 import * as asyncTriggerStore from '../services/async-trigger-store.js';
@@ -22,6 +23,7 @@ import * as sandboxStore from '../services/sandbox-store.js';
 import * as backendTypeStore from '../services/backend-type-store.js';
 import { isValidRiffBaseUrl, isValidRiffSandboxCluster } from '../adapters/backend/riff-backend.js';
 import { ensureBackendAvailable } from '../services/backend-availability.js';
+import * as persistentBackend from './persistent-backend.js';
 import * as cardPrefsStore from '../services/card-prefs-store.js';
 import * as substituteModeStore from '../services/substitute-mode-store.js';
 import { createCliAdapterSync } from '../adapters/cli/registry.js';
@@ -77,7 +79,7 @@ import { isSessionStopped } from './session-liveness.js';
 import { isSuspendableBackendType } from './persistent-backend.js';
 import { getChatMode, replyMessage, sendMessage, resolveUnionIdFromOpenId, listThreadMessages, listChatMessages, listChatMessagesUntil, listChatBotMembers, getUserProfile, getUserProfileStrict, resolveAllowedUsersWithMap } from '../im/lark/client.js';
 import { parseApiMessage, cardContentHasUpgradeFallback, resolveMergedCardContent, messageMentionsBot } from '../im/lark/message-parser.js';
-import { resumeSession, spawnDashboardSession, activateQueuedSession, closeCliMismatchedSessionsForBot, suspendActiveSessionsForBot } from './session-manager.js';
+import { resumeSession, spawnDashboardSession, activateQueuedSession, closeCliMismatchedSessionsForBot } from './session-manager.js';
 import { parseSpawnRequest } from './session-create.js';
 import { cleanupMaterializedDashboardImages, materializeDashboardImages } from './dashboard-images.js';
 import { getCliDisplayName } from '../im/lark/card-builder.js';
@@ -93,12 +95,16 @@ import { validateTriggerRequest } from '../services/trigger-types.js';
 import { resolveCliSelection, selectionKeyForBot } from '../setup/cli-selection.js';
 import { checkCliAvailability } from '../setup/cli-availability.js';
 import { enrichHistorySenders } from '../dashboard/history-senders.js';
+import { validateCodexAppManagedSendOrigin, } from '../utils/codex-app-dispatch-ledger.js';
+import { withBotTurnAdmission, withBotTurnMutation } from './bot-turn-mutation-gate.js';
+import { protectedSessionMutationReasons, } from './session-mutation-guard.js';
 import { listPendingAsks, submitAskFromDesktop } from './ask-broker.js';
 import { getMessageListenerConfig, sanitizeMessageListenerUpdate, updateMessageListenerConfig, validateMessageListenerUpdate } from '../services/message-listener-store.js';
 import { MAX_MESSAGE_LISTENER_PROMPT_BYTES, normalizeMessageListenerPreviewLimit, previewMessageListenerMatches, buildListenerBotAppIdToOpenId, collectListenerBotAppIds, renderMessageListenerInstruction, } from '../services/message-listener.js';
 import { createMessageListenerRunPreview, createMessageListenerRunPreviewTurnId, getMessageListenerRunPreview, markMessageListenerRunPreviewFailed, markMessageListenerRunPreviewTriggered, } from '../services/message-listener-run-preview-store.js';
 import { listChatMemberDisplays } from '../services/groups-store.js';
 const MESSAGE_LISTENER_PREVIEW_WINDOW_MS = 24 * 60 * 60 * 1000;
+import { SUPERVISOR_SHUTDOWN_ROUTE, isExactSupervisorShutdownRequest, } from './supervisor-shutdown-ipc.js';
 let exactChatGrantHandler = applyExactChatGrantRequest;
 /** Test seam: replace the exact-grant service without touching live Feishu/config state. */
 export function setExactChatGrantHandler(handler) {
@@ -112,6 +118,10 @@ let botAvatarChanger = null;
 export function setBotAvatarChanger(fn) {
     botAvatarChanger = fn;
 }
+let supervisorShutdownRegistration = null;
+export function setSupervisorShutdownHandler(registration) {
+    supervisorShutdownRegistration = registration;
+}
 import { composeRowFromActive, composeRowFromClosed, composeRowFromPersistedActive, feishuChatLink, setBotName as setRowsBotName, getBotName, } from './dashboard-rows.js';
 import { getBotBrand, getBot, getBotOpenId, loadBotConfigs, readBotSkillPolicy, getBotTuiSlashAllow } from '../bot-registry.js';
 import { normalizeKanbanColumn, normalizeKanbanPosition, normalizeSessionTitle } from './session-board.js';
@@ -123,6 +133,7 @@ import { normalizeSessionTitleSource, updateSessionTitle } from './session-title
 import { requestAgentSessionRename } from './session-rename.js';
 import { ChatRenameCooldown, ChatRenameSerialQueue, normalizeLarkChatName } from './chat-rename.js';
 import { sessionAnchorId, larkTransportEnabled } from './types.js';
+import { isRiffBackendSession } from './persistent-backend.js';
 import { attachSkillPolicy, detachSkillPolicy } from './skills/im-command.js';
 import { readSkillRegistry } from '../services/skill-registry-store.js';
 import { commitDeviceIsolationActivation, DEVICE_ISOLATION_COMMIT_PATH, DEVICE_ISOLATION_PREPARE_PATH, DEVICE_ISOLATION_RELEASE_PATH, logDeviceIsolationActivationError, prepareDeviceIsolationActivation, releaseDeviceIsolationActivation, } from './device-isolation-daemon.js';
@@ -149,6 +160,73 @@ export function jsonRes(res, status, body) {
     res.writeHead(status, { 'content-type': 'application/json' });
     res.end(JSON.stringify(body));
 }
+function rejectProtectedSessionMutation(res, values) {
+    const bySessionId = new Map();
+    for (const value of values) {
+        const session = 'session' in value ? value.session : value;
+        const reasons = protectedSessionMutationReasons(value);
+        if (reasons.length === 0)
+            continue;
+        const existing = bySessionId.get(session.sessionId);
+        if (existing) {
+            existing.reasons = [...new Set([...existing.reasons, ...reasons])];
+            continue;
+        }
+        bySessionId.set(session.sessionId, {
+            sessionId: session.sessionId,
+            ...(session.cliId ? { cliId: session.cliId } : {}),
+            reasons,
+        });
+    }
+    const blockingSessions = [...bySessionId.values()];
+    if (blockingSessions.length === 0)
+        return false;
+    const codexDispatchOnly = blockingSessions.every(blocker => blocker.reasons.every(reason => reason === 'codex_app_dispatch'));
+    jsonRes(res, 409, {
+        ok: false,
+        error: codexDispatchOnly
+            ? 'codex_app_dispatch_pending'
+            : 'session_mutation_pending',
+        blockingSessions,
+    });
+    return true;
+}
+ipcRoute('POST', SUPERVISOR_SHUTDOWN_ROUTE, async (req, res) => {
+    // The production server-wide HMAC gate records trusted requests here. Keep
+    // an explicit route-local check: shutdown is never a bare loopback API.
+    if (!isTrustedHostIpcRequest(req)) {
+        return jsonRes(res, 403, { ok: false, error: 'supervisor_shutdown_unauthorized' });
+    }
+    const registration = supervisorShutdownRegistration;
+    if (!registration) {
+        return jsonRes(res, 503, { ok: false, error: 'supervisor_shutdown_not_ready' });
+    }
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch {
+        return jsonRes(res, 400, { ok: false, error: 'invalid_json' });
+    }
+    if (!isExactSupervisorShutdownRequest(registration, body)) {
+        return jsonRes(res, 409, { ok: false, error: 'supervisor_shutdown_generation_mismatch' });
+    }
+    // ACK means this exact in-memory generation accepted the request; the CLI
+    // still proves OS/PM2 quiescence. Start after flushing the ACK so a long Riff
+    // drain cannot turn a valid request into an ambiguous transport timeout.
+    jsonRes(res, 202, {
+        ok: true,
+        accepted: true,
+        larkAppId: registration.larkAppId,
+        bootInstanceId: registration.bootInstanceId,
+        processStartIdentity: registration.processStartIdentity,
+    });
+    setImmediate(() => {
+        void registration.shutdown().catch(error => {
+            logger.error(`supervisor shutdown failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    });
+});
 export class JsonBodyTooLargeError extends Error {
     maxBytes;
     constructor(maxBytes) {
@@ -285,6 +363,81 @@ export async function readJsonBody(req, maxBytes) {
         return {};
     return JSON.parse(Buffer.concat(chunks).toString('utf8'));
 }
+class IpcBodyTooLargeError extends Error {
+}
+class IpcBodyTimeoutError extends Error {
+}
+/** Strict reader for the one unauthenticated capability challenge route. The
+ * generic IPC reader intentionally has no cap for trusted-host endpoints; a
+ * loopback-confined process must not be able to buffer arbitrary chunked input
+ * before its capability is checked. */
+async function readBoundedJsonBody(req, maxBytes, timeoutMs) {
+    const contentLength = req.headers['content-length'];
+    if (typeof contentLength === 'string') {
+        if (!/^\d+$/.test(contentLength) || Number(contentLength) > maxBytes) {
+            throw new IpcBodyTooLargeError('request body too large');
+        }
+    }
+    return await new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let settled = false;
+        const cleanup = () => {
+            clearTimeout(timer);
+            req.off('data', onData);
+            req.off('end', onEnd);
+            req.off('error', onError);
+            req.off('aborted', onAborted);
+        };
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            req.pause();
+            cleanup();
+            reject(err);
+        };
+        const onData = (raw) => {
+            const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+            total += chunk.length;
+            if (total > maxBytes) {
+                fail(new IpcBodyTooLargeError('request body too large'));
+                return;
+            }
+            chunks.push(chunk);
+        };
+        const onEnd = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            try {
+                resolve(chunks.length === 0
+                    ? {}
+                    : JSON.parse(Buffer.concat(chunks, total).toString('utf8')));
+            }
+            catch (err) {
+                reject(err);
+            }
+        };
+        const onError = (err) => fail(err);
+        const onAborted = () => fail(new Error('request aborted'));
+        const timer = setTimeout(() => fail(new IpcBodyTimeoutError('request body timed out')), timeoutMs);
+        timer.unref?.();
+        req.on('data', onData);
+        req.once('end', onEnd);
+        req.once('error', onError);
+        req.once('aborted', onAborted);
+    });
+}
+function closeUntrustedRequestAfterResponse(req, res) {
+    res.setHeader('connection', 'close');
+    res.once('finish', () => req.destroy());
+    // Drain whatever is already buffered until the response has been flushed;
+    // the finish hook then closes a partial/slow body instead of reusing it as a
+    // keep-alive request.
+    req.resume();
+}
 // ─── Trusted-host auth (loopback + route-bound HMAC) ────────────────────────
 //
 // Production start enables a server-wide gate: loopback is connectivity, not
@@ -381,6 +534,11 @@ function routeHasNarrowUntrustedAuth(method, pathname) {
         return true;
     if (method === 'POST' && pathname === '/api/attention')
         return true;
+    // macOS read-isolated `botmux send` presents a rotating worker capability;
+    // the handler writes the authoritative tuple into a host-owned read-only
+    // proof sidecar, so loopback response spoofing cannot confer authority.
+    if (method === 'POST' && pathname === MANAGED_ORIGIN_ATTEST_ROUTE)
+        return true;
     // Workflow v3 mutations carry their own domain-separated full-envelope
     // protocol (request signature over method/path/exact body with nonce
     // anti-replay + boot audience, signed response), keyed on the same host
@@ -439,6 +597,152 @@ ipcRoute('GET', '/healthz', (_req, res) => {
     }
     jsonRes(res, 200, { ok: true });
 });
+const MANAGED_ORIGIN_ATTEST_BODY_MAX_BYTES = 2 * 1024;
+const MANAGED_ORIGIN_ATTEST_BODY_TIMEOUT_MS = 1_000;
+const MANAGED_ORIGIN_ATTEST_MAX_PREAUTH_IN_FLIGHT = 128;
+const MANAGED_ORIGIN_ATTEST_MAX_OUTSTANDING_PER_SESSION = 64;
+const managedOriginOutstandingProofs = new Map();
+let managedOriginPreauthInFlight = 0;
+async function handleManagedOriginAttestation(req, res) {
+    let body;
+    try {
+        body = await readBoundedJsonBody(req, MANAGED_ORIGIN_ATTEST_BODY_MAX_BYTES, MANAGED_ORIGIN_ATTEST_BODY_TIMEOUT_MS);
+    }
+    catch (err) {
+        if (err instanceof IpcBodyTooLargeError || err instanceof IpcBodyTimeoutError) {
+            closeUntrustedRequestAfterResponse(req, res);
+        }
+        return jsonRes(res, err instanceof IpcBodyTooLargeError
+            ? 413
+            : err instanceof IpcBodyTimeoutError
+                ? 408
+                : 400, {
+            ok: false,
+            error: err instanceof IpcBodyTooLargeError
+                ? 'body_too_large'
+                : err instanceof IpcBodyTimeoutError
+                    ? 'body_timeout'
+                    : 'bad_json',
+        });
+    }
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return jsonRes(res, 400, { ok: false, error: 'bad_attestation_request' });
+    }
+    const sessionId = typeof body.sessionId === 'string' && body.sessionId.length <= 256
+        ? body.sessionId
+        : '';
+    const capability = typeof body.originCapability === 'string'
+        && /^[a-f0-9]{32,128}$/i.test(body.originCapability)
+        ? body.originCapability
+        : '';
+    const channelId = typeof (body.originChannelId ?? body.channelId) === 'string'
+        && /^[a-f0-9]{64}$/.test((body.originChannelId ?? body.channelId))
+        ? (body.originChannelId ?? body.channelId)
+        : '';
+    const nonce = typeof body.nonce === 'string' && /^[a-f0-9]{64}$/.test(body.nonce)
+        ? body.nonce
+        : '';
+    if (!sessionId || !channelId || !capability || !nonce) {
+        return jsonRes(res, 400, { ok: false, error: 'bad_attestation_request' });
+    }
+    const ds = findActiveBySessionId(sessionId);
+    const worker = ds?.worker;
+    let workerPidLive = false;
+    if (worker && Number.isSafeInteger(worker.pid) && (worker.pid ?? 0) > 0) {
+        try {
+            process.kill(worker.pid, 0);
+            workerPidLive = true;
+        }
+        catch { /* ESRCH/EPERM/invalid pid all fail closed */ }
+    }
+    const workerLive = !!worker
+        && worker.connected === true
+        && !worker.killed
+        && worker.exitCode === null
+        && worker.signalCode === null
+        && workerPidLive;
+    const liveTurnId = ds?.managedTurnOrigin?.turnId;
+    const verified = authorizeSessionScopedIpc({
+        trustedHost: false,
+        sessionExists: !!ds,
+        receiverSession: !!ds?.session.vcMeetingReceiver,
+        allowReceiver: true,
+        sessionId,
+        liveOrigin: ds?.managedTurnOrigin,
+        claimedCapability: capability,
+    });
+    if (!verified.ok || !ds?.managedTurnOrigin || !liveTurnId || !workerLive) {
+        return jsonRes(res, 403, { ok: false, error: 'origin_unproven' });
+    }
+    const origin = ds.managedTurnOrigin;
+    if (!origin.originChannelId || !/^[a-f0-9]{64}$/.test(origin.originChannelId)) {
+        return jsonRes(res, 403, { ok: false, error: 'origin_channel_unproven' });
+    }
+    if (channelId !== origin.originChannelId) {
+        return jsonRes(res, 403, { ok: false, error: 'origin_channel_unproven' });
+    }
+    const codexDecision = validateCodexAppManagedSendOrigin(ds.session.codexAppDispatchLedger, origin, ds.initConfig?.cliId === 'codex-app' || ds.session.cliId === 'codex-app');
+    if (!codexDecision.ok) {
+        return jsonRes(res, 409, { ok: false, error: 'origin_not_sendable' });
+    }
+    const outstanding = managedOriginOutstandingProofs.get(sessionId) ?? 0;
+    if (outstanding >= MANAGED_ORIGIN_ATTEST_MAX_OUTSTANDING_PER_SESSION) {
+        return jsonRes(res, 429, { ok: false, error: 'too_many_attestations' });
+    }
+    let proofPath;
+    try {
+        proofPath = writeManagedOriginAttestationProof({
+            dataDir: config.session.dataDir,
+            proof: {
+                domain: MANAGED_ORIGIN_PROOF_DOMAIN,
+                version: 1,
+                nonce,
+                channelId: origin.originChannelId,
+                sessionId,
+                turnId: liveTurnId,
+                ...(origin.dispatchAttempt !== undefined
+                    ? { dispatchAttempt: origin.dispatchAttempt }
+                    : {}),
+                requiresCodexAppLedger: codexDecision.requiresLedger,
+                issuedAtMs: Date.now(),
+            },
+        });
+    }
+    catch (err) {
+        logger.warn(`[managed-origin] could not write attestation proof: ${err}`);
+        return jsonRes(res, 409, { ok: false, error: 'proof_unavailable' });
+    }
+    managedOriginOutstandingProofs.set(sessionId, outstanding + 1);
+    const cleanupTimer = setTimeout(() => {
+        try {
+            unlinkSync(proofPath);
+        }
+        catch { /* expired/already gone */ }
+        const remaining = (managedOriginOutstandingProofs.get(sessionId) ?? 1) - 1;
+        if (remaining > 0)
+            managedOriginOutstandingProofs.set(sessionId, remaining);
+        else
+            managedOriginOutstandingProofs.delete(sessionId);
+    }, MANAGED_ORIGIN_PROOF_TTL_MS + 1_000);
+    cleanupTimer.unref?.();
+    return jsonRes(res, 200, { ok: true });
+}
+ipcRoute('POST', MANAGED_ORIGIN_ATTEST_ROUTE, async (req, res) => {
+    // This counter is acquired before parsing or capability lookup.  Per-session
+    // proof quotas cannot protect the unauthenticated slow-body phase because a
+    // session id is not trustworthy until the complete request has been read.
+    if (managedOriginPreauthInFlight >= MANAGED_ORIGIN_ATTEST_MAX_PREAUTH_IN_FLIGHT) {
+        closeUntrustedRequestAfterResponse(req, res);
+        return jsonRes(res, 429, { ok: false, error: 'too_many_attestation_requests' });
+    }
+    managedOriginPreauthInFlight += 1;
+    try {
+        await handleManagedOriginAttestation(req, res);
+    }
+    finally {
+        managedOriginPreauthInFlight -= 1;
+    }
+});
 export { composeRowFromActive, composeRowFromClosed, composeRowFromPersistedActive };
 // Re-export setBotName for backwards-compatible imports (daemon.ts).  Both
 // callers (this module's cachedBotName + dashboard-rows' cachedBotName) need
@@ -562,8 +866,48 @@ ipcRoute('POST', '/api/sessions/:sessionId/close', async (req, res, params) => {
     const auth = sessionCliIpcAuth(req, ds, params.sessionId, body);
     if (!auth.ok)
         return jsonRes(res, 403, { ok: false, error: auth.error });
-    const r = await closeSession(params.sessionId);
-    jsonRes(res, 200, r);
+    const initial = findSessionRecord(params.sessionId);
+    // Resolve the owning bot for the FIFO-drain gate from the live DaemonSession
+    // first (it carries larkAppId even before a persisted record exists), then the
+    // stored row, then this daemon's own identity. A trusted-host close of an
+    // already-missing session has no owner to key the gate on, so close directly:
+    // closeSession is idempotent and reports alreadyClosed.
+    const larkAppId = ds?.larkAppId || initial?.larkAppId || cachedLarkAppId;
+    if (!larkAppId) {
+        const r = await closeSession(params.sessionId);
+        return jsonRes(res, r.ok ? 200 : 502, r);
+    }
+    return withBotTurnMutation(larkAppId, async () => {
+        // Re-resolve only after every earlier admitted turn has drained. Explicit
+        // close is the abandon boundary and may clear accepted FIFO, but it must
+        // never clear a stale pre-drain snapshot while a turn is still preparing.
+        const current = findSessionRecord(params.sessionId);
+        if (current && current.status === 'closed') {
+            return jsonRes(res, 200, { ok: true, alreadyClosed: true });
+        }
+        const r = await closeSession(params.sessionId);
+        jsonRes(res, r.ok ? 200 : 502, r);
+    });
+});
+// `botmux list` zombie pruning is maintenance, not explicit abandon. Serialize
+// against inbound admission and refuse if any backend-neutral durable owner
+// became unsettled after the CLI took its liveness snapshot.
+ipcRoute('POST', '/api/sessions/:sessionId/prune', async (_req, res, params) => {
+    const initial = findSessionRecord(params.sessionId);
+    if (!initial)
+        return jsonRes(res, 404, { ok: false, error: 'session_not_found' });
+    const larkAppId = initial.larkAppId || cachedLarkAppId;
+    if (!larkAppId)
+        return jsonRes(res, 503, { ok: false, error: 'bot_not_found' });
+    return withBotTurnMutation(larkAppId, async () => {
+        const current = findSessionRecord(params.sessionId);
+        if (!current)
+            return jsonRes(res, 404, { ok: false, error: 'session_not_found' });
+        if (rejectProtectedSessionMutation(res, [current]))
+            return;
+        const r = await closeSession(params.sessionId);
+        jsonRes(res, r.ok ? 200 : 502, r);
+    });
 });
 /** Post a scope-aware "restarting" notice into the session's Lark thread/chat,
  *  mirroring the /resume route — so a Feishu-side observer sees why the CLI just
@@ -599,69 +943,93 @@ function postRestartNotice(ds, fresh) {
             .catch(err => logger.debug(`[restart] failed to post thread-scope restart notice: ${err}`));
     }
 }
-ipcRoute('POST', '/api/sessions/:sessionId/restart', (_req, res, params) => {
-    const ds = findActiveBySessionId(params.sessionId);
-    if (!ds)
+ipcRoute('POST', '/api/sessions/:sessionId/restart', async (_req, res, params) => {
+    const initial = findActiveBySessionId(params.sessionId);
+    if (!initial)
         return jsonRes(res, 404, { ok: false, error: 'session_not_active' });
-    if (isSessionTransferring(ds)) {
-        return jsonRes(res, 409, { ok: false, error: 'session_transferring' });
-    }
-    // Adopt/observed sessions: botmux never owned the CLI — restarting would kill
-    // the user's real tmux/zellij pane. Hard-reject (the worker self-guards too).
-    if (ds.adoptedFrom || ds.initConfig?.adoptMode) {
-        return jsonRes(res, 409, { ok: false, error: 'adopt_restart_unsupported' });
-    }
-    const cliId = ds.session.cliId ?? 'unknown';
-    if (ds.worker && !ds.worker.killed) {
-        // Live worker → in-place CLI restart (kills the CLI, respawns with --resume).
-        // 捎带最新 per-bot env：dashboard 改完 env 后重启才真正生效（与 /restart 同逻辑）。
-        try {
-            ds.workerReady = false;
-            ds.worker.send({ type: 'restart', env: latestPerBotEnvForRestart(ds) });
+    return withBotTurnMutation(initial.larkAppId, () => {
+        const ds = findActiveBySessionId(params.sessionId);
+        if (!ds)
+            return jsonRes(res, 404, { ok: false, error: 'session_not_active' });
+        if (isSessionTransferring(ds)) {
+            return jsonRes(res, 409, { ok: false, error: 'session_transferring' });
         }
-        catch (err) {
-            return jsonRes(res, 502, { ok: false, error: String(err) });
+        // Adopt/observed sessions: botmux never owned the CLI — restarting would kill
+        // the user's real tmux/zellij pane. Hard-reject (the worker self-guards too).
+        if (ds.adoptedFrom || ds.initConfig?.adoptMode) {
+            return jsonRes(res, 409, { ok: false, error: 'adopt_restart_unsupported' });
+        }
+        // Riff owns a remote task lineage. Its worker deliberately refuses restart
+        // because destroy + respawn would sever or replace that lineage. Reject at
+        // the daemon boundary so the dashboard never reports HTTP 200 for a no-op.
+        if (isRiffBackendSession(ds)) {
+            return jsonRes(res, 409, {
+                ok: false,
+                error: 'riff_restart_unsupported',
+                message: t('cmd.restart.riff_unsupported', undefined, localeForBot(ds.larkAppId)),
+            });
         }
-        postRestartNotice(ds, false);
-        return jsonRes(res, 200, { ok: true, sessionId: params.sessionId, cliId, revived: false });
-    }
-    // Worker is gone but the session is still active — idle-suspended (over the
-    // per-bot cap), lazy-restored after a daemon restart, or crash-loop-stopped.
-    // Revive it the same way the Feishu card restart does (forkWorker), so the
-    // dashboard isn't a dead-end: a 409 here would leave NO working control to
-    // bring the CLI back (the resume button only shows for closed sessions).
-    forkWorker(ds, '', ds.hasHistory);
-    postRestartNotice(ds, true);
-    jsonRes(res, 200, { ok: true, sessionId: params.sessionId, cliId, revived: true });
+        if (rejectProtectedSessionMutation(res, [ds]))
+            return;
+        const cliId = ds.session.cliId ?? 'unknown';
+        if (ds.worker && !ds.worker.killed) {
+            // Live worker → in-place CLI restart (kills the CLI, respawns with --resume).
+            // 捎带最新 per-bot env：dashboard 改完 env 后重启才真正生效（与 /restart 同逻辑）。
+            try {
+                ds.workerReady = false;
+                ds.worker.send({ type: 'restart', reason: 'operator', env: latestPerBotEnvForRestart(ds) });
+            }
+            catch (err) {
+                return jsonRes(res, 502, { ok: false, error: String(err) });
+            }
+            postRestartNotice(ds, false);
+            return jsonRes(res, 200, { ok: true, sessionId: params.sessionId, cliId, revived: false });
+        }
+        // Worker is gone but the session is still active — idle-suspended (over the
+        // per-bot cap), lazy-restored after a daemon restart, or crash-loop-stopped.
+        // Revive it the same way the Feishu card restart does (forkWorker), so the
+        // dashboard isn't a dead-end: a 409 here would leave NO working control to
+        // bring the CLI back (the resume button only shows for closed sessions).
+        forkWorker(ds, '', ds.hasHistory);
+        postRestartNotice(ds, true);
+        jsonRes(res, 200, { ok: true, sessionId: params.sessionId, cliId, revived: true });
+    });
 });
 /** Manually suspend one active session: kill the worker + CLI/pane, session
  *  stays active and cold-resumes from its transcript on the next message —
  *  the same semantics the idle-worker sweeper applies over the live cap.
  *  Primary use: `botmux suspend --isolated` after a credential rotation, so
  *  isolated bots' next cold spawn re-provisions the freshest creds. */
-ipcRoute('POST', '/api/sessions/:sessionId/suspend', (_req, res, params) => {
-    const ds = findActiveBySessionId(params.sessionId);
-    if (!ds)
+ipcRoute('POST', '/api/sessions/:sessionId/suspend', async (_req, res, params) => {
+    const initial = findActiveBySessionId(params.sessionId);
+    if (!initial)
         return jsonRes(res, 404, { ok: false, error: 'session_not_active' });
-    if (isSessionTransferring(ds)) {
-        return jsonRes(res, 409, { ok: false, error: 'session_transferring' });
-    }
-    // Adopt/observed sessions: botmux never owned the CLI — suspending would kill
-    // the user's real tmux/zellij pane. Same guard as /restart.
-    if (ds.adoptedFrom || ds.initConfig?.adoptMode) {
-        return jsonRes(res, 409, { ok: false, error: 'adopt_suspend_unsupported' });
-    }
-    if (!ds.worker || ds.worker.killed) {
-        // Worker already gone (idle-suspended / crash-stopped) — the goal state is
-        // already reached, so report idempotent success without a live kill.
-        return jsonRes(res, 200, { ok: true, sessionId: params.sessionId, suspended: false, reason: 'no_live_worker' });
-    }
-    if (!suspendWorker(ds, 'manual_suspend')) {
-        // Live worker but a non-suspendable (pty) backend: killing it would drop the
-        // in-memory conversation with no persistent pane to resume from lazily.
-        return jsonRes(res, 409, { ok: false, error: 'backend_not_suspendable' });
-    }
-    jsonRes(res, 200, { ok: true, sessionId: params.sessionId, suspended: true });
+    return withBotTurnMutation(initial.larkAppId, () => {
+        const ds = findActiveBySessionId(params.sessionId);
+        if (!ds)
+            return jsonRes(res, 404, { ok: false, error: 'session_not_active' });
+        if (isSessionTransferring(ds)) {
+            return jsonRes(res, 409, { ok: false, error: 'session_transferring' });
+        }
+        // Adopt/observed sessions: botmux never owned the CLI — suspending would kill
+        // the user's real tmux/zellij pane. Same guard as /restart.
+        if (ds.adoptedFrom || ds.initConfig?.adoptMode) {
+            return jsonRes(res, 409, { ok: false, error: 'adopt_suspend_unsupported' });
+        }
+        if (rejectProtectedSessionMutation(res, [ds]))
+            return;
+        if (!ds.worker || ds.worker.killed) {
+            // Worker already gone (idle-suspended / crash-stopped) — the goal state is
+            // already reached, so report idempotent success without a live kill.
+            return jsonRes(res, 200, { ok: true, sessionId: params.sessionId, suspended: false, reason: 'no_live_worker' });
+        }
+        if (!suspendWorker(ds, 'manual_suspend')) {
+            // Live worker but a non-suspendable (pty) backend: killing it would drop the
+            // in-memory conversation with no persistent pane to resume from lazily.
+            return jsonRes(res, 409, { ok: false, error: 'backend_not_suspendable' });
+        }
+        jsonRes(res, 200, { ok: true, sessionId: params.sessionId, suspended: true });
+    });
 });
 /**
  * Count host-overload降压 candidates for THIS daemon's scope, so the alert card
@@ -916,6 +1284,16 @@ ipcRoute('POST', '/api/sessions/:sessionId/cd', async (req, res, params) => {
     if (ds.adoptedFrom || ds.initConfig?.adoptMode) {
         return jsonRes(res, 409, { ok: false, error: 'adopt_cd_unsupported' });
     }
+    // Riff restart/kill is intentionally refused to preserve remote task
+    // lineage. Reject before validation/repin so the persisted cwd cannot drift
+    // from the still-running sandbox.
+    if (isRiffBackendSession(ds)) {
+        return jsonRes(res, 409, {
+            ok: false,
+            error: 'riff_cd_unsupported',
+            message: t('cmd.cd.riff_unsupported', undefined, localeForBot(ds.larkAppId)),
+        });
+    }
     // ownAppId 收窄到本 bot 自己的角色库子树：不收窄就能切进别的 bot 的角色目录，
     // 下面 repinSessionWorkingDir 把 ds.workingDir 钉过去之后，那个 bot 的沙盒会话
     // 就拿到了对方整棵角色库的 readWrite（打穿 fs-policy 的跨 bot 隔离）。
@@ -1085,45 +1463,103 @@ ipcRoute('POST', '/api/sessions/:sessionId/board', async (req, res, params) => {
     const session = findOwnedSessionRecord(params.sessionId);
     if (!session)
         return jsonRes(res, 404, { ok: false, error: 'session_not_found' });
-    // 待办池(queued)会话被拖到「进行中」= 激活：把暂存内容当首轮发给 CLI 开跑。
-    // activateQueuedSession 内部会清 queued + 把列设成 in_progress + forkWorker。
-    const activeDs = findActiveBySessionId(params.sessionId);
-    if (column === 'in_progress' && activeDs?.session.queued) {
-        await activateQueuedSession(activeDs);
+    const larkAppId = session.larkAppId || cachedLarkAppId;
+    if (!larkAppId)
+        return jsonRes(res, 503, { ok: false, error: 'bot_not_found' });
+    return withBotTurnAdmission(larkAppId, async () => {
+        const currentSession = findSessionRecord(params.sessionId);
+        if (!currentSession)
+            return jsonRes(res, 404, { ok: false, error: 'session_not_found' });
+        // 待办池(queued)会话被拖到「进行中」= 激活：把暂存内容当首轮发给 CLI 开跑。
+        // activateQueuedSession 内部会清 queued + 把列设成 in_progress + forkWorker。
+        const activeDs = findActiveBySessionId(params.sessionId);
+        let activationTransferred = false;
+        if (column === 'in_progress' && activeDs?.session.queued) {
+            const activated = await activateQueuedSession(activeDs);
+            if (!activated.ok)
+                return jsonRes(res, 500, activated);
+            activationTransferred = true;
+        }
+        else if (column) {
+            currentSession.kanbanColumn = column;
+        }
+        if (position !== null)
+            currentSession.kanbanPosition = position;
+        try {
+            sessionStore.updateSession(currentSession);
+        }
+        catch (err) {
+            if (!activationTransferred)
+                throw err;
+            logger.error(`[dashboard] board metadata persistence failed after queued activation ownership transferred: `
+                + `${err instanceof Error ? err.message : String(err)}`);
+        }
+        dashboardEventBus.publish({
+            type: 'session.update',
+            body: {
+                sessionId: params.sessionId,
+                // queued 一并下发：激活后 session.queued 已为 false，前端浅合并若不带这个字段
+                // 会残留 queued=true（卡片仍显示「开始」、再点 409）。!!session.queued 始终反映现态。
+                patch: { kanbanColumn: currentSession.kanbanColumn, kanbanPosition: currentSession.kanbanPosition, queued: !!currentSession.queued },
+            },
+        });
+        jsonRes(res, 200, { ok: true });
+    });
+});
+// Narrow CLI whiteboard binding mutation. Keeping this daemon-side avoids a
+// short-lived `botmux whiteboard` process rewriting a stale whole Session row
+// over a concurrent Codex App FIFO transition.
+ipcRoute('POST', '/api/sessions/:sessionId/whiteboard', async (req, res, params) => {
+    let body;
+    try {
+        body = await readJsonBody(req);
     }
-    else if (column) {
-        session.kanbanColumn = column;
+    catch {
+        return jsonRes(res, 400, { ok: false, error: 'bad_json' });
     }
-    if (position !== null)
-        session.kanbanPosition = position;
-    sessionStore.updateSession(session);
-    dashboardEventBus.publish({
-        type: 'session.update',
-        body: {
-            sessionId: params.sessionId,
-            // queued 一并下发：激活后 session.queued 已为 false，前端浅合并若不带这个字段
-            // 会残留 queued=true（卡片仍显示「开始」、再点 409）。!!session.queued 始终反映现态。
-            patch: { kanbanColumn: session.kanbanColumn, kanbanPosition: session.kanbanPosition, queued: !!session.queued },
-        },
+    if (typeof body.whiteboardId !== 'string'
+        || body.whiteboardId.length === 0
+        || body.whiteboardId.length > 256) {
+        return jsonRes(res, 400, { ok: false, error: 'bad_whiteboard_id' });
+    }
+    const session = findSessionRecord(params.sessionId);
+    if (!session)
+        return jsonRes(res, 404, { ok: false, error: 'session_not_found' });
+    const larkAppId = session.larkAppId || cachedLarkAppId;
+    if (!larkAppId)
+        return jsonRes(res, 503, { ok: false, error: 'bot_not_found' });
+    return withBotTurnAdmission(larkAppId, async () => {
+        const current = findSessionRecord(params.sessionId);
+        if (!current)
+            return jsonRes(res, 404, { ok: false, error: 'session_not_found' });
+        current.whiteboardId = body.whiteboardId;
+        sessionStore.updateSession(current);
+        jsonRes(res, 200, { ok: true, whiteboardId: current.whiteboardId });
     });
-    jsonRes(res, 200, { ok: true });
 });
 // 待办池会话「开始」：把 parked 会话激活（发首轮、起 CLI），与拖到「进行中」同义。
 ipcRoute('POST', '/api/sessions/:sessionId/start', async (_req, res, params) => {
-    const ds = findActiveBySessionId(params.sessionId);
-    if (!ds)
+    const initial = findActiveBySessionId(params.sessionId);
+    if (!initial)
         return jsonRes(res, 404, { ok: false, error: 'session_not_found' });
-    if (!ds.session.queued)
-        return jsonRes(res, 409, { ok: false, error: 'not_queued' });
-    const r = await activateQueuedSession(ds);
-    if (!r.ok)
-        return jsonRes(res, 500, r);
-    sessionStore.updateSession(ds.session);
-    dashboardEventBus.publish({
-        type: 'session.update',
-        body: { sessionId: params.sessionId, patch: { kanbanColumn: ds.session.kanbanColumn, queued: false } },
+    return withBotTurnAdmission(initial.larkAppId, async () => {
+        const ds = findActiveBySessionId(params.sessionId);
+        if (!ds)
+            return jsonRes(res, 404, { ok: false, error: 'session_not_found' });
+        if (!ds.session.queued)
+            return jsonRes(res, 409, { ok: false, error: 'not_queued' });
+        const r = await activateQueuedSession(ds);
+        if (!r.ok)
+            return jsonRes(res, 500, r);
+        dashboardEventBus.publish({
+            type: 'session.update',
+            body: {
+                sessionId: params.sessionId,
+                patch: { kanbanColumn: ds.session.kanbanColumn, queued: !!ds.session.queued },
+            },
+        });
+        jsonRes(res, 200, { ok: true });
     });
-    jsonRes(res, 200, { ok: true });
 });
 // Dashboard「创建会话」spawn：在新建的群里为本 daemon 的 bot 拉起/暂存一条 chat-scope
 // 会话。aggregator 建完群后按模式(一起开工/lead 分配)对每个目标 bot 的 daemon 调一次。
@@ -1144,32 +1580,34 @@ ipcRoute('POST', '/api/sessions/spawn', async (req, res) => {
     if (!parsed.ok)
         return jsonRes(res, 400, { ok: false, error: parsed.error });
     const postBanner = !!body.postBanner;
-    let attachments;
-    try {
-        attachments = materializeDashboardImages(cachedLarkAppId, parsed.value.images);
-    }
-    catch (err) {
-        logger.error(`[createSession] failed to persist Dashboard images: ${err?.message ?? err}`);
-        return jsonRes(res, 500, { ok: false, error: 'image_store_failed' });
-    }
-    const r = await spawnDashboardSession(activeSessions, undefined, {
-        larkAppId: cachedLarkAppId,
-        chatId: parsed.value.chatId,
-        content: parsed.value.content,
-        column: parsed.value.column,
-        role: parsed.value.role,
-        coworkers: parsed.value.coworkers,
-        attachments,
-        title: parsed.value.title,
-        postBanner,
-        ownerOpenId: parsed.value.ownerOpenId,
-        ownerUnionId: parsed.value.ownerUnionId,
+    return withBotTurnAdmission(cachedLarkAppId, async () => {
+        let attachments;
+        try {
+            attachments = materializeDashboardImages(cachedLarkAppId, parsed.value.images);
+        }
+        catch (err) {
+            logger.error(`[createSession] failed to persist Dashboard images: ${err?.message ?? err}`);
+            return jsonRes(res, 500, { ok: false, error: 'image_store_failed' });
+        }
+        const r = await spawnDashboardSession(activeSessions, undefined, {
+            larkAppId: cachedLarkAppId,
+            chatId: parsed.value.chatId,
+            content: parsed.value.content,
+            column: parsed.value.column,
+            role: parsed.value.role,
+            coworkers: parsed.value.coworkers,
+            attachments,
+            title: parsed.value.title,
+            postBanner,
+            ownerOpenId: parsed.value.ownerOpenId,
+            ownerUnionId: parsed.value.ownerUnionId,
+        });
+        if (!r.ok) {
+            cleanupMaterializedDashboardImages(cachedLarkAppId, attachments);
+            return jsonRes(res, r.error === 'session_exists' ? 409 : 500, r);
+        }
+        jsonRes(res, 200, r);
     });
-    if (!r.ok) {
-        cleanupMaterializedDashboardImages(cachedLarkAppId, attachments);
-        return jsonRes(res, r.error === 'session_exists' ? 409 : 500, r);
-    }
-    jsonRes(res, 200, r);
 });
 ipcRoute('POST', '/api/chat-reply-mode', async (req, res) => {
     if (!cachedLarkAppId)
@@ -1558,71 +1996,80 @@ function workingDirForSession(sessionId) {
  */
 ipcRoute('POST', '/api/sessions/:sessionId/resume', async (req, res, params) => {
     const sessionId = params.sessionId;
-    const reg = getActiveSessionsRegistry();
-    if (!reg)
-        return jsonRes(res, 503, { ok: false, error: 'registry_unavailable' });
-    const result = await resumeSession(sessionId, reg);
-    if (!result.ok) {
-        const status = result.error === 'not_found' ? 404 : 409;
-        return jsonRes(res, status, { ok: false, error: result.error, activeSessionId: result.activeSessionId });
-    }
-    const ds = result.ds;
-    // `?wake=1` is an opt-in operational hook (no UI/CLI caller wires it today —
-    // it's meant for direct `curl` recovery): instead of the default lazy
-    // cold-resume on the next inbound message, fork the worker immediately so the
-    // session is usable right away. Off by default keeps every existing caller's
-    // behaviour unchanged.
-    const wake = new URL(req.url ?? '/', 'http://localhost').searchParams.get('wake') === '1';
-    // Tell the dashboard the row flipped back to active (mirror of session.update
-    // emitted by closeSession). Use `null` for closedAt — `undefined` would be
-    // dropped by JSON.stringify on the SSE wire and the aggregator's spread
-    // (`{...cur, ...patch}`) would leave the stale closedAt in place.
-    dashboardEventBus.publish({
-        type: 'session.update',
-        body: {
-            sessionId,
-            patch: { status: 'active', closedAt: null },
-        },
-    });
-    // Notify the original chat so humans see why the session is alive again.
-    // Routing follows session.scope — thread-scope replies into the thread root
-    // (reply_in_thread=true), chat-scope posts a plain message to the chat (any
-    // reply_in_thread call would silently get rejected or land on a stale root).
-    const cliId = ds.session.cliId;
-    const botCfg = ds.larkAppId ? getBot(ds.larkAppId).config : undefined;
-    const cliName = sessionConfiguredRuntimeDisplayName(ds.session, botCfg?.cliRuntime)
-        ?? getCliDisplayName(cliId ?? botCfg?.cliId ?? 'claude-code');
-    const notice = JSON.stringify({ text: `🔄 会话已通过命令行恢复，发条消息继续与 ${cliName} 对话。` });
-    if (ds.larkAppId && !sessionTransportDisabled(ds)) {
-        if (ds.scope === 'chat' && ds.chatId) {
-            getChatMode(ds.larkAppId, ds.chatId, { forceRefresh: true })
-                .then((mode) => mode === 'topic' && ds.session.rootMessageId
-                ? replyMessage(ds.larkAppId, ds.session.rootMessageId, notice, 'text', true)
-                : sendMessage(ds.larkAppId, ds.chatId, notice, 'text'))
-                .catch(err => logger.debug(`[resume] failed to post chat-scope resume notice: ${err}`));
+    const sourceSession = findSessionRecord(sessionId);
+    if (!sourceSession)
+        return jsonRes(res, 404, { ok: false, error: 'not_found' });
+    // Legacy persisted sessions may carry an empty larkAppId and are hydrated
+    // with this daemon's identity by resumeSession. Use the same fallback for
+    // admission instead of rejecting an otherwise valid recovery record.
+    const larkAppId = sourceSession.larkAppId || cachedLarkAppId || '__legacy_unbound__';
+    return withBotTurnAdmission(larkAppId, async () => {
+        const reg = getActiveSessionsRegistry();
+        if (!reg)
+            return jsonRes(res, 503, { ok: false, error: 'registry_unavailable' });
+        const result = await resumeSession(sessionId, reg);
+        if (!result.ok) {
+            const status = result.error === 'not_found' ? 404 : 409;
+            return jsonRes(res, status, { ok: false, error: result.error, activeSessionId: result.activeSessionId });
+        }
+        const ds = result.ds;
+        // `?wake=1` is an opt-in operational hook (no UI/CLI caller wires it today —
+        // it's meant for direct `curl` recovery): instead of the default lazy
+        // cold-resume on the next inbound message, fork the worker immediately so the
+        // session is usable right away. Off by default keeps every existing caller's
+        // behaviour unchanged.
+        const wake = new URL(req.url ?? '/', 'http://localhost').searchParams.get('wake') === '1';
+        // Tell the dashboard the row flipped back to active (mirror of session.update
+        // emitted by closeSession). Use `null` for closedAt — `undefined` would be
+        // dropped by JSON.stringify on the SSE wire and the aggregator's spread
+        // (`{...cur, ...patch}`) would leave the stale closedAt in place.
+        dashboardEventBus.publish({
+            type: 'session.update',
+            body: {
+                sessionId,
+                patch: { status: 'active', closedAt: null },
+            },
+        });
+        // Notify the original chat so humans see why the session is alive again.
+        // Routing follows session.scope — thread-scope replies into the thread root
+        // (reply_in_thread=true), chat-scope posts a plain message to the chat (any
+        // reply_in_thread call would silently get rejected or land on a stale root).
+        const cliId = ds.session.cliId;
+        const botCfg = ds.larkAppId ? getBot(ds.larkAppId).config : undefined;
+        const cliName = sessionConfiguredRuntimeDisplayName(ds.session, botCfg?.cliRuntime)
+            ?? getCliDisplayName(cliId ?? botCfg?.cliId ?? 'claude-code');
+        const notice = JSON.stringify({ text: `🔄 会话已通过命令行恢复，发条消息继续与 ${cliName} 对话。` });
+        if (ds.larkAppId && !sessionTransportDisabled(ds)) {
+            if (ds.scope === 'chat' && ds.chatId) {
+                getChatMode(ds.larkAppId, ds.chatId, { forceRefresh: true })
+                    .then((mode) => mode === 'topic' && ds.session.rootMessageId
+                    ? replyMessage(ds.larkAppId, ds.session.rootMessageId, notice, 'text', true)
+                    : sendMessage(ds.larkAppId, ds.chatId, notice, 'text'))
+                    .catch(err => logger.debug(`[resume] failed to post chat-scope resume notice: ${err}`));
+            }
+            else if (ds.session.rootMessageId) {
+                replyMessage(ds.larkAppId, ds.session.rootMessageId, notice, 'text', true)
+                    .catch(err => logger.debug(`[resume] failed to post thread-scope resume notice: ${err}`));
+            }
         }
-        else if (ds.session.rootMessageId) {
-            replyMessage(ds.larkAppId, ds.session.rootMessageId, notice, 'text', true)
-                .catch(err => logger.debug(`[resume] failed to post thread-scope resume notice: ${err}`));
+        // Report the EFFECTIVE action, not the raw request flag: only fork when wake
+        // was asked AND there's no live worker to clobber. (resumeSession always hands
+        // back a worker:null ds today, so this matches `wake` in practice — but
+        // reporting the action keeps the response honest if the guard ever broadens.)
+        const woke = wake && (!ds.worker || ds.worker.killed);
+        if (woke) {
+            forkWorker(ds, '', true);
         }
-    }
-    // Report the EFFECTIVE action, not the raw request flag: only fork when wake
-    // was asked AND there's no live worker to clobber. (resumeSession always hands
-    // back a worker:null ds today, so this matches `wake` in practice — but
-    // reporting the action keeps the response honest if the guard ever broadens.)
-    const woke = wake && (!ds.worker || ds.worker.killed);
-    if (woke) {
-        forkWorker(ds, '', true);
-    }
-    jsonRes(res, 200, {
-        ok: true,
-        sessionId,
-        wake: woke,
-        title: ds.session.title,
-        chatId: ds.chatId,
-        rootMessageId: ds.session.rootMessageId,
-        workingDir: ds.session.workingDir,
-        cliId,
+        jsonRes(res, 200, {
+            ok: true,
+            sessionId,
+            wake: woke,
+            title: ds.session.title,
+            chatId: ds.chatId,
+            rootMessageId: ds.session.rootMessageId,
+            workingDir: ds.session.workingDir,
+            cliId,
+        });
     });
 });
 /**
@@ -2074,15 +2521,22 @@ ipcRoute('POST', '/api/trigger', async (req, res) => {
         const result = await triggerSessionTurn(valid.request, { larkAppId: cachedLarkAppId, activeSessions });
         const status = result.ok
             ? 200
-            : result.errorCode === 'bot_not_in_chat'
-                ? 403
-                : result.errorCode === 'session_not_found'
-                    ? 404
-                    : result.errorCode === 'wait_timeout'
-                        ? 504
-                        : result.errorCode === 'target_required' || result.errorCode === 'bad_request'
-                            ? 400
-                            : 500;
+            // An idempotent retry that resolves to a durable `failed` async state is a
+            // successful HTTP call reporting a terminal outcome (like a 200 completed/
+            // queued), not a request error — surface it 200 so the caller reads `state`.
+            : result.state === 'failed'
+                ? 200
+                : result.errorCode === 'idempotency_conflict'
+                    ? 409
+                    : result.errorCode === 'bot_not_in_chat'
+                        ? 403
+                        : result.errorCode === 'session_not_found'
+                            ? 404
+                            : result.errorCode === 'wait_timeout'
+                                ? 504
+                                : result.errorCode === 'target_required' || result.errorCode === 'bad_request'
+                                    ? 400
+                                    : 500;
         return jsonRes(res, status, result);
     }
     catch (e) {
@@ -3021,6 +3475,7 @@ ipcRoute('GET', '/api/bot-default-oncall', async (_req, res) => {
         restrictGrantCommands: grantPrefs.restrictGrantCommands,
         autoGrantRequestCards: grantPrefs.autoGrantRequestCards,
         messageQuotaDefaultLimit: grantPrefs.messageQuotaDefaultLimit,
+        grantDefaultDurationMs: grantPrefs.grantDefaultDurationMs,
         p2pMode,
         skillInjection,
         skillInjectionSupport,
@@ -3190,7 +3645,8 @@ ipcRoute('PUT', '/api/bot-summary-trigger', async (req, res) => {
 // Per-bot 授权偏好。Body 任意子集：
 //   • restrictGrantCommands: boolean       — 限制被授权人只能纯对话
 //   • autoGrantRequestCards: boolean       — 未授权 @ 被挡住时是否发 grant 申请卡
-//   • messageQuotaDefaultLimit: number|null — 卡片默认额度覆盖（null = 产品默认 3 条）
+//   • messageQuotaDefaultLimit: number|null — 卡片/Oncall 额度覆盖（null = 卡片内置 3 条、Oncall 不限）
+//   • grantDefaultDurationMs: number|null   — 新授权默认有限时长（null = 产品默认 1 小时）
 ipcRoute('PUT', '/api/bot-grant-prefs', async (req, res) => {
     if (!cachedLarkAppId)
         return jsonRes(res, 503, { error: 'larkAppId_not_set' });
@@ -3211,11 +3667,16 @@ ipcRoute('PUT', '/api/bot-grant-prefs', async (req, res) => {
         patch.restrictGrantCommands = body.restrictGrantCommands;
     if (typeof body.autoGrantRequestCards === 'boolean')
         patch.autoGrantRequestCards = body.autoGrantRequestCards;
-    // null（含 JSON null）= 关闭默认额度；number = 设定（store 内再校验正整数）。
+    // null（含 JSON null）= 恢复内置额度策略；number = 设定覆盖值（store 内校验 1–1000）。
     if (body.messageQuotaDefaultLimit === null)
         patch.messageQuotaDefaultLimit = null;
     else if (typeof body.messageQuotaDefaultLimit === 'number')
         patch.messageQuotaDefaultLimit = body.messageQuotaDefaultLimit;
+    // null = 恢复产品默认 1 小时；number 由 store 按卡片有限选项白名单校验。
+    if (body.grantDefaultDurationMs === null)
+        patch.grantDefaultDurationMs = null;
+    else if (typeof body.grantDefaultDurationMs === 'number')
+        patch.grantDefaultDurationMs = body.grantDefaultDurationMs;
     if (Object.keys(patch).length === 0)
         return jsonRes(res, 400, { ok: false, error: 'no_valid_fields' });
     const r = await grantPrefsStore.updateBotGrantPrefs(cachedLarkAppId, patch);
@@ -3343,6 +3804,7 @@ ipcRoute('PUT', '/api/bot-avatar', async (req, res) => {
 ipcRoute('PUT', '/api/bot-agent', async (req, res) => {
     if (!cachedLarkAppId)
         return jsonRes(res, 503, { error: 'larkAppId_not_set' });
+    const larkAppId = cachedLarkAppId;
     let body;
     try {
         body = await readJsonBody(req);
@@ -3361,7 +3823,7 @@ ipcRoute('PUT', '/api/bot-agent', async (req, res) => {
         return jsonRes(res, 400, { ok: false, error: 'invalid_cli', message: err?.message ?? String(err) });
     }
     const model = typeof body.model === 'string' ? body.model.trim() : '';
-    const currentBotConfig = getBot(cachedLarkAppId).config;
+    const currentBotConfig = getBot(larkAppId).config;
     const runtimeFieldPresent = Object.prototype.hasOwnProperty.call(body, 'cliRuntime');
     const currentSelectionKey = selectionKeyForBot(currentBotConfig.cliId, currentBotConfig.wrapperCli);
     const selectionChanged = key !== currentSelectionKey;
@@ -3436,94 +3898,109 @@ ipcRoute('PUT', '/api/bot-agent', async (req, res) => {
     const availabilityWarning = availability.available
         ? undefined
         : `配置已保存，但所选 Agent 当前无法启动：${availability.reason ?? '本地启动依赖不可用'}。请先在 daemon 所在机器安装或修正 PATH / CLI 路径。`;
-    // If the new CLI/wrapper can no longer enforce a currently-on read isolation,
-    // auto-clear the flag here so the next session doesn't fail-close on it. (The
-    // read-isolation toggle validates at enable time; changing the agent afterwards
-    // is the other way a bot could end up configured-but-unenforceable.)
-    let readIsolationCleared = false;
-    const r = await rmwBotEntry(cachedLarkAppId, (entry) => {
-        entry.cliId = selected.cliId;
+    return withBotTurnMutation(larkAppId, async () => {
+        // Agent selection can replace every live worker generation and may also
+        // auto-clear readIsolation. Close admission and drain in-flight acceptance
+        // before inspecting both the registry and restart source of truth. A
+        // settings mutation is not an explicit abandon boundary: an unsettled
+        // Codex App FIFO must survive unchanged for recovery.
+        const activeBotSessions = listActiveSessions().filter(ds => ds.larkAppId === larkAppId);
+        const persistedActiveBotSessions = sessionStore.listSessions().filter(session => session.status === 'active'
+            && (session.larkAppId === larkAppId || !session.larkAppId));
+        if (rejectProtectedSessionMutation(res, [
+            ...activeBotSessions,
+            ...persistedActiveBotSessions,
+        ]))
+            return;
+        // If the new CLI/wrapper can no longer enforce a currently-on read isolation,
+        // auto-clear the flag here so the next session doesn't fail-close on it. (The
+        // read-isolation toggle validates at enable time; changing the agent afterwards
+        // is the other way a bot could end up configured-but-unenforceable.)
+        let readIsolationCleared = false;
+        const r = await rmwBotEntry(larkAppId, (entry) => {
+            entry.cliId = selected.cliId;
+            if (selected.wrapperCli)
+                entry.wrapperCli = selected.wrapperCli;
+            else
+                delete entry.wrapperCli;
+            if (nextRuntime) {
+                entry.cliRuntime = nextRuntime;
+                // Downgrade shadow: older BotMux versions ignore cliRuntime but retain
+                // cliPathOverride, so a rollback still launches this distribution.
+                entry.cliPathOverride = nextRuntime.executable;
+            }
+            else if (nextLegacyPath) {
+                entry.cliPathOverride = nextLegacyPath;
+                delete entry.cliRuntime;
+            }
+            else {
+                delete entry.cliRuntime;
+                delete entry.cliPathOverride;
+            }
+            if (model)
+                entry.model = model;
+            else
+                delete entry.model;
+            if (entry.readIsolation === true &&
+                !readIsolationEnforceableFor({ cliId: selected.cliId, cliPathOverride: effectivePath, wrapperCli: selected.wrapperCli })) {
+                delete entry.readIsolation;
+                readIsolationCleared = true;
+            }
+            // cliId=riff → backendType 自动设为 riff（否则 spawn 走 pty 后端找不到本地二进制）。
+            if (selected.cliId === 'riff') {
+                entry.backendType = 'riff';
+            }
+            else if (entry.backendType === 'riff') {
+                // 从 riff 切回其它 CLI：清掉这个自动配对的 backend override，回落 daemon
+                // 默认后端——否则新 CLI 会跑在 RiffBackend 上（PTY 分块输入被当成一串 riff
+                // 任务）。手动的 pty/tmux/herdr/zellij override 不受影响（它们不会是 riff）。
+                delete entry.backendType;
+            }
+            return { write: true, result: null };
+        });
+        if (!r.ok)
+            return jsonRes(res, 400, { ok: false, error: r.reason });
+        const bot = getBot(larkAppId);
+        bot.config.cliId = selected.cliId;
+        bot.config.cliRuntime = nextRuntime;
+        bot.config.cliPathOverride = nextRuntime?.executable ?? nextLegacyPath;
         if (selected.wrapperCli)
-            entry.wrapperCli = selected.wrapperCli;
+            bot.config.wrapperCli = selected.wrapperCli;
         else
-            delete entry.wrapperCli;
-        if (nextRuntime) {
-            entry.cliRuntime = nextRuntime;
-            // Downgrade shadow: older BotMux versions ignore cliRuntime but retain
-            // cliPathOverride, so a rollback still launches this distribution.
-            entry.cliPathOverride = nextRuntime.executable;
-        }
-        else if (nextLegacyPath) {
-            entry.cliPathOverride = nextLegacyPath;
-            delete entry.cliRuntime;
-        }
-        else {
-            delete entry.cliRuntime;
-            delete entry.cliPathOverride;
-        }
-        if (model)
-            entry.model = model;
-        else
-            delete entry.model;
-        if (entry.readIsolation === true &&
-            !readIsolationEnforceableFor({ cliId: selected.cliId, cliPathOverride: effectivePath, wrapperCli: selected.wrapperCli })) {
-            delete entry.readIsolation;
-            readIsolationCleared = true;
-        }
-        // cliId=riff → backendType 自动设为 riff（否则 spawn 走 pty 后端找不到本地二进制）。
+            bot.config.wrapperCli = undefined;
+        bot.config.model = model || undefined;
+        if (readIsolationCleared)
+            bot.config.readIsolation = false;
         if (selected.cliId === 'riff') {
-            entry.backendType = 'riff';
+            bot.config.backendType = 'riff';
         }
-        else if (entry.backendType === 'riff') {
-            // 从 riff 切回其它 CLI：清掉这个自动配对的 backend override，回落 daemon
-            // 默认后端——否则新 CLI 会跑在 RiffBackend 上（PTY 分块输入被当成一串 riff
-            // 任务）。手动的 pty/tmux/herdr/zellij override 不受影响（它们不会是 riff）。
-            delete entry.backendType;
+        else if (bot.config.backendType === 'riff') {
+            bot.config.backendType = undefined;
         }
-        return { write: true, result: null };
-    });
-    if (!r.ok)
-        return jsonRes(res, 400, { ok: false, error: r.reason });
-    const bot = getBot(cachedLarkAppId);
-    bot.config.cliId = selected.cliId;
-    bot.config.cliRuntime = nextRuntime;
-    bot.config.cliPathOverride = nextRuntime?.executable ?? nextLegacyPath;
-    if (selected.wrapperCli)
-        bot.config.wrapperCli = selected.wrapperCli;
-    else
-        bot.config.wrapperCli = undefined;
-    bot.config.model = model || undefined;
-    if (readIsolationCleared)
-        bot.config.readIsolation = false;
-    if (selected.cliId === 'riff') {
-        bot.config.backendType = 'riff';
-    }
-    else if (bot.config.backendType === 'riff') {
-        bot.config.backendType = undefined;
-    }
-    // 热切后立刻清掉本 bot 名下失配的存量会话——否则它们冻结的旧 CLI 会被下一条
-    // 消息 lazy resume 复活，要等下次 daemon 重启才被 restore 守卫清理。
-    const closedMismatchedSessions = await closeCliMismatchedSessionsForBot(cachedLarkAppId);
-    const selectionKey = selectionKeyForBot(selected.cliId, selected.wrapperCli);
-    jsonRes(res, 200, {
-        ok: true,
-        cliId: selected.cliId,
-        cliRuntime: nextRuntime ?? null,
-        cliPathOverride: nextRuntime ? null : nextLegacyPath ?? null,
-        wrapperCli: selected.wrapperCli ?? null,
-        model: model || null,
-        selectionKey,
-        closedMismatchedSessions,
-        // Report the (possibly auto-cleared) read-isolation state + whether the new
-        // agent can still enforce it, so the dashboard updates its toggle immediately
-        // instead of showing a stale enabled/supported state until a full refetch.
-        readIsolation: bot.config.readIsolation === true,
-        readIsolationSupported: readIsolationEnforceableFor(bot.config),
-        readIsolationCleared,
-        agentAvailable: availability.available,
-        availabilityWarning,
-        requiredCommand: availability.command,
-        runtimeProbe,
+        // 热切后立刻清掉本 bot 名下失配的存量会话——否则它们冻结的旧 CLI 会被下一条
+        // 消息 lazy resume 复活，要等下次 daemon 重启才被 restore 守卫清理。
+        const closedMismatchedSessions = await closeCliMismatchedSessionsForBot(larkAppId);
+        const selectionKey = selectionKeyForBot(selected.cliId, selected.wrapperCli);
+        jsonRes(res, 200, {
+            ok: true,
+            cliId: selected.cliId,
+            cliRuntime: nextRuntime ?? null,
+            cliPathOverride: nextRuntime ? null : nextLegacyPath ?? null,
+            wrapperCli: selected.wrapperCli ?? null,
+            model: model || null,
+            selectionKey,
+            closedMismatchedSessions,
+            // Report the (possibly auto-cleared) read-isolation state + whether the new
+            // agent can still enforce it, so the dashboard updates its toggle immediately
+            // instead of showing a stale enabled/supported state until a full refetch.
+            readIsolation: bot.config.readIsolation === true,
+            readIsolationSupported: readIsolationEnforceableFor(bot.config),
+            readIsolationCleared,
+            agentAvailable: availability.available,
+            availabilityWarning,
+            requiredCommand: availability.command,
+            runtimeProbe,
+        });
     });
 });
 // Per-bot 私聊单聊模式 p2pMode。Body `{ p2pMode: 'chat' | 'thread' }`:
@@ -3905,6 +4382,9 @@ ipcRoute('PUT', '/api/bot-sandbox', async (req, res) => {
     catch {
         return jsonRes(res, 400, { ok: false, error: 'bad_json' });
     }
+    // File-sandbox policy is frozen onto each Session at creation and reused on
+    // restore; this toggle is intentionally next-session-only and cannot mutate
+    // a live pane's profile.
     const r = await sandboxStore.updateBotSandbox(cachedLarkAppId, body.enabled === true);
     if (!r.ok)
         return jsonRes(res, 400, { ok: false, error: r.reason });
@@ -3941,6 +4421,7 @@ ipcRoute('PUT', '/api/bot-sandbox-paths', async (req, res) => {
 ipcRoute('PUT', '/api/bot-read-isolation', async (req, res) => {
     if (!cachedLarkAppId)
         return jsonRes(res, 503, { error: 'larkAppId_not_set' });
+    const larkAppId = cachedLarkAppId;
     let body;
     try {
         body = await readJsonBody(req);
@@ -3949,23 +4430,94 @@ ipcRoute('PUT', '/api/bot-read-isolation', async (req, res) => {
         return jsonRes(res, 400, { ok: false, error: 'bad_json' });
     }
     const enable = body.enabled === true;
-    // The worker FAIL-CLOSES (refuses to start the session) for a configured
-    // readIsolation that can't be enforced: non-darwin, an adapter without
-    // supportsReadIsolation, or a wrapperCli gateway. Reject enabling it in exactly
-    // those cases so the toggle can never brick the bot's next session. (Turning it
-    // OFF is always allowed — recovers a flag that became unenforceable.)
-    if (enable && !readIsolationEnforceable(cachedLarkAppId)) {
-        return jsonRes(res, 400, { ok: false, error: 'read_isolation_unenforceable' });
-    }
-    const r = await sandboxStore.updateBotReadIsolation(cachedLarkAppId, enable);
-    if (!r.ok)
-        return jsonRes(res, 400, { ok: false, error: r.reason });
-    // Read isolation only takes effect at COLD spawn (provisionIsolatedBotHome +
-    // Seatbelt wrapper run then). Suspend this bot's active sessions so the next
-    // message cold-restarts under the new state — otherwise close+resume would keep
-    // running the old, un-provisioned state and the toggle would silently no-op.
-    const suspendedSessions = await suspendActiveSessionsForBot(cachedLarkAppId);
-    jsonRes(res, 200, { ok: true, readIsolation: r.readIsolation, suspendedSessions });
+    return withBotTurnMutation(larkAppId, async () => {
+        // An idempotent request changes neither the durable policy nor any pane.
+        // Return before pending/active/teardown guards so a dashboard refresh that
+        // repeats the authoritative value cannot be rejected merely because the
+        // bot is doing work.
+        if (sandboxStore.getBotReadIsolation(larkAppId) === enable) {
+            return jsonRes(res, 200, {
+                ok: true,
+                readIsolation: enable,
+                suspendedSessions: 0,
+                changed: false,
+            });
+        }
+        // Close admission first and drain handlers that may already be awaiting
+        // downloads/noteTurnReceived. Ledger preflight alone cannot see those
+        // pre-accept turns; draining prevents a post-sweep send into a killed ds.
+        const activeBotSessions = listActiveSessions().filter(ds => ds.larkAppId === larkAppId);
+        // Registry state alone is insufficient: partial restore, an anchor
+        // collision, or a failed staggered reattach can omit a durable active row
+        // while its persistent pane still survives. Consult the same persisted
+        // session source a restart will hydrate. Legacy unscoped active rows are
+        // conservatively treated as this daemon's until explicitly closed.
+        const persistedBotSessions = sessionStore.listSessions().filter(session => session.larkAppId === larkAppId || !session.larkAppId);
+        const persistedActiveBotSessions = persistedBotSessions.filter(session => session.status === 'active');
+        if (rejectProtectedSessionMutation(res, [
+            ...activeBotSessions,
+            ...persistedActiveBotSessions,
+        ]))
+            return;
+        // Crash-transactional safety boundary: bots.json is the restart source of
+        // truth, while a live tmux/herdr/zellij pane retains its old in-memory
+        // Seatbelt profile. Persisting the new flag before tearing those panes down
+        // creates an unrecoverable crash window because the restart path cannot
+        // prove which exact read/write isolation profile a surviving pane runs.
+        // Require explicit close first; with no active logical session there is no
+        // owned pane a restart can reattach under the newly persisted policy.
+        if (activeBotSessions.length > 0 || persistedActiveBotSessions.length > 0) {
+            return jsonRes(res, 409, {
+                ok: false,
+                error: 'read_isolation_active_sessions',
+            });
+        }
+        // `/close` intentionally returns after sending worker close IPC and marking
+        // the row closed; persistent-pane destruction can lag. A closed row's pid
+        // is deliberately not probed: PID alone has no birth identity and may have
+        // been reused by an unrelated process. closeSession clears it atomically.
+        // For current rows, the stamped persistent backend is the teardown proof.
+        // Pre-stamp closed rows are not synchronously probed across three CLIs here:
+        // that legacy shell fan-out blocks the daemon event loop, while any active
+        // legacy row has already failed the active-session guard above.
+        for (const session of persistedBotSessions) {
+            if (session.adoptedFrom || session.title?.startsWith('Adopt:'))
+                continue;
+            const backendTypes = persistentBackend.isSuspendableBackendType(session.backendType)
+                ? [session.backendType]
+                : [];
+            for (const backendType of backendTypes) {
+                const backingName = persistentBackend.persistentSessionName(backendType, session.sessionId);
+                if (persistentBackend.probePersistentSession(backendType, backingName) !== 'missing') {
+                    return jsonRes(res, 409, {
+                        ok: false,
+                        error: 'read_isolation_teardown_unverified',
+                    });
+                }
+            }
+        }
+        // The worker FAIL-CLOSES (refuses to start the session) for a configured
+        // readIsolation that cannot be enforced. Check this after the active-session
+        // safety boundary so even an unsupported enable cannot obscure a surviving
+        // old-policy pane with a less important validation error.
+        if (enable && !readIsolationEnforceable(larkAppId)) {
+            return jsonRes(res, 400, { ok: false, error: 'read_isolation_unenforceable' });
+        }
+        // With the gate closed and no active logical session, persistence is the
+        // only mutation. updateBotReadIsolation writes bots.json atomically and
+        // then publishes the same value to the daemon runtime before resolving.
+        // A crash at any point can only lead to a cold spawn under the old or new
+        // durable policy; there is no owned pane to reattach.
+        const r = await sandboxStore.updateBotReadIsolation(larkAppId, enable);
+        if (!r.ok)
+            return jsonRes(res, 400, { ok: false, error: r.reason });
+        jsonRes(res, 200, {
+            ok: true,
+            readIsolation: r.readIsolation,
+            suspendedSessions: 0,
+            changed: true,
+        });
+    });
 });
 // Per-bot session backend override (pty | tmux | herdr | zellij | zmx), or clear it
 // ('' / 'auto' / null → follow the daemon default). next-session 生效：running
@@ -4357,6 +4909,8 @@ export function startIpcServer(opts) {
                     return jsonRes(res, 401, { ok: false, error: 'unauthorized', reason: auth.reason });
                 }
             }
+            if (!publicRoute && opts.ready)
+                await opts.ready;
             for (const r of routes) {
                 if (r.method !== req.method)
                     continue;