@pinet/slack-bridge 0.2.2 → 0.2.6

package/dist/index.js

@@ -1,20 +1,24 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
-import { createGitContextCache, probeGitBranch, probeGitContext } from "./git-metadata.js";
-import { loadSettings as loadSettingsFromFile, buildAllowlist, reloadPinetRuntimeSafely, buildPinetOwnerToken, resolveAgentIdentity, resolveBrokerStableId, resolveAgentStableId, resolveAllowAllWorkspaceUsers, trackBrokerInboundThread, } from "./helpers.js";
+import { probeGitBranch, probeGitContext } from "./git-metadata.js";
+import { loadSettings as loadSettingsFromFile, buildAllowlist, resolvePinetMeshAuth, reloadPinetRuntimeInPlaceSafely, reloadPinetRuntimeSafely, buildPinetOwnerToken, resolveAgentIdentity, resolveBrokerStableId, resolveAgentStableId, resolveAllowAllWorkspaceUsers, trackBrokerInboundThread, isAbortError, } from "./helpers.js";
 import { buildSecurityPrompt } from "./guardrails.js";
 import { TtlCache, TtlSet } from "./ttl-cache.js";
 import { resolveReactionCommands } from "./reaction-triggers.js";
-import { DEFAULT_SOCKET_PATH } from "./broker/client.js";
+import { inspectBrokerLock, probeBrokerSocket, replaceBrokerOwner, } from "./broker/index.js";
+import { readMeshSecret } from "./broker/auth.js";
+import { collectAgentLifecycleStatuses, } from "@pinet/broker-core";
+import { resolveHibernationSettings } from "./hibernation-config.js";
 import { createCommandRegistrationRuntime } from "./command-registration-runtime.js";
 import { createToolRegistrationRuntime } from "./tool-registration-runtime.js";
 import { createSlackRuntimeAccess } from "./slack-runtime-access.js";
 import { createThreadConfirmationPolicy } from "./thread-confirmations.js";
 import { persistDeliveredInboundMessage } from "./broker-inbound-persistence.js";
+import { createCompactionGate } from "./compaction-gate.js";
 import { createIMessageAdapter, detectIMessageMvpEnvironment, formatIMessageMvpReadiness, } from "@pinet/imessage-bridge";
 import { SLACK_SOCKET_DELIVERY_DEDUP_MAX_SIZE, SLACK_SOCKET_DELIVERY_DEDUP_TTL_MS, } from "./slack-access.js";
 import { createFollowerDeliveryState, markFollowerInboxIdsDelivered, queueFollowerInboxIds, } from "./follower-delivery.js";
-import { createFollowerRuntime } from "./follower-runtime.js";
+import { createFollowerRuntime, resolveBrokerSocketPath, } from "./follower-runtime.js";
 import { createSinglePlayerRuntime, } from "./single-player-runtime.js";
 import { createBrokerRuntime } from "./broker-runtime.js";
 import { createSlackPinetRuntimeAdapterFactory } from "./slack-pinet-runtime-adapter.js";
@@ -42,7 +46,8 @@ import { formatSlackAgentsDashboard, formatSlackAgentsUsage, isSlackAgentCommand
 import { createPinetRegistrationGate } from "./pinet-registration-gate.js";
 import { createBrokerRuntimeAccess } from "./broker-runtime-access.js";
 import { createInboxDrainRuntime } from "./inbox-drain-runtime.js";
-import { createSubtreeBrokerRuntime } from "./subtree-broker-runtime.js";
+import { createSubtreeBrokerRuntime, getExtensionEntryPath, SUBTREE_INHERITED_ENV_KEYS, } from "./subtree-broker-runtime.js";
+import { routeHibernationCommand } from "./broker/hibernation-command-router.js";
 import { createAgentCompletionRuntime } from "./agent-completion-runtime.js";
 import { sendBrokerMessage } from "./broker/message-send.js";
 import { SlackThreadStatusManager } from "./slack-thread-status.js";
@@ -144,13 +149,20 @@ export default function (pi) {
         },
     });
     const { updateBadge, setExtStatus, maybeDrainInboxIfIdle } = sessionUiRuntime;
+    const compactionGate = createCompactionGate(() => {
+        maybeDrainInboxIfIdle();
+        const ctx = sessionUiRuntime.getExtensionContext();
+        if (ctx)
+            subtreeBrokerRuntime.drainInbox(ctx);
+    });
+    const isIdleAndNotCompacting = () => !compactionGate.isActive() && (sessionUiRuntime.getExtensionContext()?.isIdle?.() ?? true);
     let reportAgentStatus = async () => { };
     let deliverTrackedSlackFollowUpMessage = () => false;
     const inboxDrainRuntime = createInboxDrainRuntime({
         sendUserMessage: (body) => {
             pi.sendUserMessage(body);
         },
-        isIdle: () => sessionUiRuntime.getExtensionContext()?.isIdle?.() ?? true,
+        isIdle: isIdleAndNotCompacting,
         takeInboxMessages: (maxMessages) => inbox.splice(0, maxMessages ?? inbox.length),
         restoreInboxMessages: (messages) => {
             inbox.unshift(...messages);
@@ -166,12 +178,31 @@ export default function (pi) {
         markBrokerInboxIdsDelivered: (inboxIds) => {
             brokerRuntime.markDelivered(inboxIds);
         },
+        markSubtreeInboxIdsDelivered: (inboxIds) => {
+            subtreeBrokerRuntime.markDelivered(inboxIds);
+        },
         getFollowerDeliveryState: () => followerDeliveryState,
     });
     const { deliverFollowUpMessage, flushDeliveredFollowerAcks, drainInbox } = inboxDrainRuntime;
     drainInboxPort = drainInbox;
+    function deliverSteeringMessage(text, ctx) {
+        try {
+            return compactionGate.tryDeliver(() => {
+                if (ctx.isIdle?.() ?? true) {
+                    pi.sendUserMessage(text);
+                }
+                else {
+                    pi.sendUserMessage(text, { deliverAs: "steer" });
+                }
+            });
+        }
+        catch (error) {
+            console.error(`[slack-bridge] Pinet steering delivery failed: ${msg(error)}`);
+            return false;
+        }
+    }
     // ─── Helpers ─────────────────────────────────────────
-    const gitContextCache = createGitContextCache(() => probeGitContext(process.cwd()));
+    let gitContext = null;
     const runtimeAgentContext = createRuntimeAgentContext({
         cwd: process.cwd(),
         getSettings: () => settings,
@@ -230,7 +261,10 @@ export default function (pi) {
         getExtensionContext: sessionUiRuntime.getExtensionContext,
         persistState,
         updateBadge,
-        getGitContext: () => gitContextCache.get(),
+        getGitContext: async (signal) => {
+            gitContext ??= await probeGitContext(process.cwd(), undefined, signal);
+            return gitContext;
+        },
     });
     const { isUserAllowed, maybeWarnSlackUserAccess, maybeWarnSlackGuardrailPosture, applyLocalAgentIdentity, refreshSettings, snapshotReloadableRuntime, restoreReloadableRuntime, getAgentMetadata, getMeshRoleFromMetadata, buildSkinMetadata, applyRegistrationIdentity, } = runtimeAgentContext;
     async function refreshSlackScopeDiagnostics(ctx) {
@@ -371,7 +405,6 @@ export default function (pi) {
         beginThreadStatus: (channel, threadTs, status) => slackThreadStatuses.begin(channel, threadTs, status),
         updateThreadStatus: (channel, threadTs, status) => slackThreadStatuses.update(channel, threadTs, status),
         clearThreadStatus: (channel, threadTs) => slackThreadStatuses.clear(channel, threadTs),
-        beforeAgentStart: agentPromptGuidance.beforeAgentStart,
         onCompletionAgentEnd: agentCompletionRuntime.onAgentEnd,
         setDeliverTrackedSlackFollowUpMessage: (deliver) => {
             deliverTrackedSlackFollowUpMessage = deliver;
@@ -380,7 +413,7 @@ export default function (pi) {
     const pinetMaintenanceDelivery = createPinetMaintenanceDelivery({
         getActiveBrokerDb,
         getActiveBrokerSelfId,
-        isIdle: () => sessionUiRuntime.getExtensionContext()?.isIdle?.() ?? true,
+        isIdle: isIdleAndNotCompacting,
         sendUserMessage: (body) => {
             pi.sendUserMessage(body);
         },
@@ -420,8 +453,15 @@ export default function (pi) {
         pushInboxMessages: (messages) => {
             inbox.push(...messages);
         },
+        discardQueuedInboxMessages: () => {
+            for (let index = inbox.length - 1; index >= 0; index -= 1) {
+                if (inbox[index]?.brokerInboxOrigin === "subtree")
+                    inbox.splice(index, 1);
+            }
+        },
         updateBadge,
         maybeDrainInboxIfIdle,
+        deliverSteeringMessage,
         requestRemoteControl,
         runRemoteControl,
         formatError: msg,
@@ -499,6 +539,9 @@ export default function (pi) {
     let currentRuntimeMode = "off";
     let brokerRole = null;
     let brokerClient = null;
+    let pinetLifecycleTail = Promise.resolve();
+    let pinetReloadPromise = null;
+    let pendingStartup = null;
     let followerRuntimeDiagnostic = null;
     const followerDeliveryState = createFollowerDeliveryState();
     let desiredAgentStatus = "idle";
@@ -531,6 +574,7 @@ export default function (pi) {
         getAppToken: () => appToken,
         getAllowedUsers: () => allowedUsers,
         shouldAllowAllWorkspaceUsers: () => resolveAllowAllWorkspaceUsers(settings, process.env.SLACK_ALLOW_ALL_WORKSPACE_USERS),
+        setExtStatus,
         onAppHomeOpened: handleBrokerAppHomeOpened,
         onSlashCommand: handleBrokerSlackSlashCommand,
     });
@@ -615,6 +659,7 @@ export default function (pi) {
         },
         updateBadge,
         maybeDrainInboxIfIdle,
+        deliverSteeringMessage,
         requestRemoteControl,
         deferControlAck: deferBrokerControlAck,
         runRemoteControl,
@@ -644,6 +689,14 @@ export default function (pi) {
         buildControlPlaneDashboardSnapshot: (input) => buildBrokerControlPlaneDashboardSnapshot(input),
         buildCurrentDashboardSnapshot: async (openedAt) => buildCurrentBrokerControlPlaneDashboardSnapshot(openedAt),
         createAdapterBindings: [slackPinetAdapterFactory],
+        onAdminShutdownRequested: async (ctx) => {
+            // `/pinet start replace` from another local session: stop being the
+            // broker but keep this session alive (issue #951).
+            ctx.ui.notify("Pinet broker shutdown requested by another local session (/pinet start replace). Stopping the broker runtime in this session.", "warning");
+            await runPinetLifecycle(() => stopPinetRuntime(ctx, { releaseIdentity: true }));
+            slackRequestRuntime.reset();
+            singlePlayerRuntime.resetShutdownState();
+        },
         onMaintenanceResult: (ctx, { result, previousSignature, signature }) => {
             if (signature && signature !== previousSignature) {
                 ctx.ui.notify(`Pinet broker: ${result.anomalies.join("; ")}`, "warning");
@@ -734,6 +787,25 @@ export default function (pi) {
         },
     });
     const { sendPinetAgentMessage, sendPinetBroadcastMessage, scheduleBrokerWakeup, scheduleFollowerWakeup, listBrokerAgents, listFollowerAgents, searchPinetSessions, } = pinetMeshOps;
+    async function runHibernationCommand(command, target, reason) {
+        // Thin wrapper: DB-topology resolution + executor composition live in the
+        // extracted, independently-tested production router, so the live extension and
+        // the production-route E2E drive the exact same integration code. `brokerRole`,
+        // the runtime-activation authority (via the router's internal
+        // `hibernationRuntimeActive()` gate), the real subtree control accessor, and the
+        // central-DB fallback are all threaded through unchanged.
+        return routeHibernationCommand({
+            command,
+            target,
+            ...(reason !== undefined ? { reason } : {}),
+            brokerRole,
+            hib: resolveHibernationSettings(settings),
+            getRuntimeControl: () => subtreeBrokerRuntime.getHibernationRuntimeControl(),
+            getFallbackDb: () => getActiveBrokerDb(),
+            extensionEntryPath: getExtensionEntryPath(),
+            inheritedEnvKeys: SUBTREE_INHERITED_ENV_KEYS,
+        });
+    }
     async function listPinetLanes(options) {
         if (brokerRole === "broker") {
             const db = getActiveBrokerDb();
@@ -880,104 +952,185 @@ export default function (pi) {
         }
         throw new Error("Pinet is in an unexpected state.");
     }
-    async function transitionToRuntimeMode(ctx, mode) {
-        if (currentRuntimeMode === mode) {
-            if (mode === "off") {
-                setExtStatus(ctx, "off");
-            }
+    function runPinetLifecycle(operation) {
+        const run = pinetLifecycleTail.then(operation, operation);
+        pinetLifecycleTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async function cancelPendingStartup() {
+        const startup = pendingStartup;
+        if (!startup)
             return;
-        }
-        if (currentRuntimeMode !== "off") {
-            await stopPinetRuntime(ctx, { releaseIdentity: true });
-            // Runtime transitions keep the extension alive in-process, so restore a
-            // fresh top-level Slack request tracker after tearing the prior runtime down.
+        startup.controller.abort();
+        await startup.promise;
+    }
+    function runRuntimeModeTransition(ctx, mode, signal) {
+        return runPinetLifecycle(async () => {
+            signal?.throwIfAborted();
+            if (currentRuntimeMode === mode) {
+                if (mode === "off") {
+                    setExtStatus(ctx, "off");
+                }
+                await toolRegistrationRuntime.sync(pi, currentRuntimeMode);
+                return;
+            }
+            if (currentRuntimeMode !== "off") {
+                if (pinetReloadPromise) {
+                    await pinetReloadPromise.catch(() => undefined);
+                }
+                await stopPinetRuntime(ctx, { releaseIdentity: true });
+                signal?.throwIfAborted();
+            }
             slackRequestRuntime.reset();
             singlePlayerRuntime.resetShutdownState();
-        }
-        if (mode === "off") {
-            currentRuntimeMode = "off";
-            setExtStatus(ctx, "off");
-            return;
-        }
-        if (mode === "single") {
-            currentRuntimeMode = "single";
-            setExtStatus(ctx, "reconnecting");
-            await singlePlayerRuntime.connect(ctx);
-            botUserId = singlePlayerRuntime.getBotUserId() ?? botUserId;
+            if (mode === "off") {
+                currentRuntimeMode = "off";
+                setExtStatus(ctx, "off");
+                return;
+            }
+            if (mode === "single") {
+                currentRuntimeMode = "single";
+                setExtStatus(ctx, "reconnecting");
+                await singlePlayerRuntime.connect(ctx, signal);
+                signal?.throwIfAborted();
+                botUserId = singlePlayerRuntime.getBotUserId() ?? botUserId;
+                await toolRegistrationRuntime.sync(pi, currentRuntimeMode);
+                signal?.throwIfAborted();
+                void ensureSlackScopeDiagnostics(ctx);
+                return;
+            }
+            if (mode === "broker") {
+                await connectAsBroker(ctx, {}, signal);
+                signal?.throwIfAborted();
+                void ensureSlackScopeDiagnostics(ctx);
+                return;
+            }
+            await connectAsFollower(ctx, signal);
+            signal?.throwIfAborted();
             void ensureSlackScopeDiagnostics(ctx);
-            return;
+        });
+    }
+    async function transitionToRuntimeMode(ctx, mode) {
+        await cancelPendingStartup();
+        await runRuntimeModeTransition(ctx, mode);
+    }
+    /**
+     * Resolve the local mesh secret value for client-side broker RPCs
+     * (graceful takeover). Returns null when no secret is configured or the
+     * secret file is unreadable — callers degrade to fenced termination.
+     */
+    function resolveLocalMeshSecretValue() {
+        const meshAuth = resolvePinetMeshAuth(settings);
+        if (meshAuth.meshSecret) {
+            return meshAuth.meshSecret;
         }
-        if (mode === "broker") {
-            await connectAsBroker(ctx);
-            void ensureSlackScopeDiagnostics(ctx);
-            return;
+        try {
+            return meshAuth.meshSecretPath ? readMeshSecret(meshAuth.meshSecretPath) : readMeshSecret();
+        }
+        catch {
+            return null;
         }
-        await connectAsFollower(ctx);
-        void ensureSlackScopeDiagnostics(ctx);
     }
     async function stopPinetRuntime(ctx, options) {
         flushPersist();
         await subtreeBrokerRuntime.stop({ releaseIdentity: options.releaseIdentity });
         await brokerRuntime.disconnect({ releaseIdentity: options.releaseIdentity });
-        if (brokerClient) {
-            if (options.releaseIdentity) {
-                await disconnectFollower(ctx).catch(() => {
-                    /* best effort */
-                });
-            }
-            else {
-                await followerRuntime.disconnect(ctx, { releaseIdentity: false }).catch(() => {
-                    /* best effort */
-                });
-                brokerClient = null;
-                desiredAgentStatus = "idle";
-                brokerRole = null;
-                pinetEnabled = false;
-            }
-        }
+        await followerRuntime
+            .disconnect(ctx, { releaseIdentity: options.releaseIdentity })
+            .catch(() => {
+            /* best effort */
+        });
+        brokerClient = null;
+        followerRuntimeDiagnostic = null;
         await singlePlayerRuntime.disconnect();
         brokerRole = null;
         pinetEnabled = false;
         desiredAgentStatus = "idle";
         currentRuntimeMode = "off";
         setExtStatus(ctx, "off");
+        await toolRegistrationRuntime.sync(pi, currentRuntimeMode);
     }
     async function reloadPinetRuntime(ctx) {
-        await reloadPinetRuntimeSafely({
-            getCurrentRole: () => brokerRole,
-            snapshotState: () => snapshotReloadableRuntime(),
-            restoreState: (snapshot) => {
-                restoreReloadableRuntime(snapshot);
-            },
-            refreshState: () => {
-                refreshSettings();
-            },
-            validateRefreshedState: () => {
+        await cancelPendingStartup();
+        if (pinetReloadPromise) {
+            await pinetReloadPromise;
+            return;
+        }
+        const reloadWork = runPinetLifecycle(async () => {
+            let reloadBrokerInPlace = false;
+            const validateRefreshedState = () => {
                 if (!botToken || !appToken) {
                     throw new Error("Slack tokens are not configured after reload.");
                 }
-            },
-            stopRuntime: async () => {
-                await stopPinetRuntime(ctx, { releaseIdentity: false });
-                // Reload intentionally keeps the extension alive in-process, so restore a
-                // fresh top-level Slack request tracker after aborting the previous
-                // generation. This preserves shutdown abort semantics without leaving
-                // top-level Slack tools permanently stuck in "shutdown in progress".
-                slackRequestRuntime.reset();
-                singlePlayerRuntime.resetShutdownState();
-                setExtStatus(ctx, "reconnecting");
-            },
-            startRuntime: async (role) => {
-                if (role === "broker") {
-                    await connectAsBroker(ctx);
-                    return;
+                if (brokerRole === "broker") {
+                    reloadBrokerInPlace = brokerRuntime.canReloadInPlace();
                 }
-                await connectAsFollower(ctx);
-            },
+            };
+            if (brokerRole === "broker") {
+                await reloadPinetRuntimeInPlaceSafely({
+                    snapshotState: () => snapshotReloadableRuntime(),
+                    restoreState: (snapshot) => {
+                        restoreReloadableRuntime(snapshot);
+                    },
+                    refreshState: () => {
+                        refreshSettings();
+                    },
+                    validateRefreshedState,
+                    reloadRuntime: async () => {
+                        if (reloadBrokerInPlace) {
+                            const result = await brokerRuntime.reloadAdapters(ctx);
+                            botUserId = result.botUserId;
+                            await toolRegistrationRuntime.sync(pi, currentRuntimeMode);
+                            return;
+                        }
+                        await stopPinetRuntime(ctx, { releaseIdentity: false });
+                        slackRequestRuntime.reset();
+                        singlePlayerRuntime.resetShutdownState();
+                        setExtStatus(ctx, "reconnecting");
+                        await connectAsBroker(ctx, { refreshSettings: false });
+                    },
+                });
+                return;
+            }
+            await reloadPinetRuntimeSafely({
+                getCurrentRole: () => brokerRole,
+                snapshotState: () => snapshotReloadableRuntime(),
+                restoreState: (snapshot) => {
+                    restoreReloadableRuntime(snapshot);
+                },
+                refreshState: () => {
+                    refreshSettings();
+                },
+                validateRefreshedState,
+                stopRuntime: async () => {
+                    await stopPinetRuntime(ctx, { releaseIdentity: false });
+                    // Reload intentionally keeps the extension alive in-process, so restore a
+                    // fresh top-level Slack request tracker after aborting the previous
+                    // generation. This preserves shutdown abort semantics without leaving
+                    // top-level Slack tools permanently stuck in "shutdown in progress".
+                    slackRequestRuntime.reset();
+                    singlePlayerRuntime.resetShutdownState();
+                    setExtStatus(ctx, "reconnecting");
+                },
+                startRuntime: async (role) => {
+                    if (role === "broker") {
+                        await connectAsBroker(ctx);
+                        return;
+                    }
+                    await connectAsFollower(ctx);
+                },
+            });
+        }).finally(() => {
+            if (pinetReloadPromise === reloadWork) {
+                pinetReloadPromise = null;
+            }
         });
+        pinetReloadPromise = reloadWork;
+        await reloadWork;
     }
     // ─── Tools ──────────────────────────────────────────
     const toolRegistrationRuntime = createToolRegistrationRuntime({
+        buildPromptGuidelines: agentPromptGuidance.buildPromptGuidelines,
         slackTools: {
             getBotToken: () => {
                 if (!botToken) {
@@ -994,6 +1147,9 @@ export default function (pi) {
             getAgentOwnerToken: () => agentOwnerToken,
             getLastDmChannel: () => lastDmChannel,
             updateBadge,
+            markSubtreeInboxIdsDelivered: (inboxIds) => {
+                subtreeBrokerRuntime.markDelivered(inboxIds);
+            },
             resolveUser,
             threadContext: singlePlayerRuntime.getThreadContextPort(),
             resolveChannel,
@@ -1002,6 +1158,7 @@ export default function (pi) {
             getBotUserId: () => botUserId,
             registerConfirmationRequest,
             pinetDelivery: {
+                isEnabled: () => pinetEnabled,
                 isAvailable: () => pinetEnabled && brokerRole !== null,
                 sendSlackMessage: async (input) => {
                     const content = {
@@ -1093,6 +1250,21 @@ export default function (pi) {
             ralphSnoozeStatus: () => currentRuntimeMode === "broker" ? brokerRuntime.getRalphSnoozeStatus() : null,
             snoozeRalphLoop: (input) => brokerRuntime.snoozeRalphLoop(input),
             clearRalphSnooze: () => brokerRuntime.clearRalphSnooze(),
+            runHibernateCommand: ({ target, reason }) => runHibernationCommand("hibernate", target, reason),
+            runWakeCommand: ({ target, reason }) => runHibernationCommand("wake", target, reason),
+            getAgentLifecycleProjection: (agentIds) => {
+                if (brokerRole !== "broker")
+                    return [];
+                const db = getActiveBrokerDb();
+                if (!db)
+                    return [];
+                const hib = resolveHibernationSettings(settings);
+                return collectAgentLifecycleStatuses(db, {
+                    ...(agentIds ? { agentIds } : {}),
+                    maxConcurrentWakes: hib.maxConcurrentWakes,
+                    maxConcurrentWakesPerRepo: hib.maxConcurrentWakesPerRepo,
+                });
+            },
         },
         iMessageTools: {
             pinetEnabled: () => pinetEnabled,
@@ -1122,11 +1294,16 @@ export default function (pi) {
     });
     toolRegistrationRuntime.register(pi);
     // ─── Commands ───────────────────────────────────────
-    async function connectAsBroker(ctx) {
-        refreshSettings();
+    async function connectAsBroker(ctx, options = {}, signal) {
+        signal?.throwIfAborted();
+        setExtStatus(ctx, "reconnecting");
+        if (options.refreshSettings !== false) {
+            refreshSettings();
+        }
         maybeWarnSlackUserAccess(ctx);
         maybeWarnSlackGuardrailPosture(ctx);
-        const { botUserId: brokerBotUserId, recoveredBrokerMessages, recoveredTargetedBacklogCount, releasedBrokerClaims, } = await brokerRuntime.connect(ctx);
+        const { botUserId: brokerBotUserId, recoveredBrokerMessages, recoveredTargetedBacklogCount, releasedBrokerClaims, } = await brokerRuntime.connect(ctx, signal);
+        signal?.throwIfAborted();
         const broker = brokerRuntime.getBroker();
         if (!broker) {
             throw new Error("Broker runtime failed to initialize.");
@@ -1148,8 +1325,18 @@ export default function (pi) {
             else {
                 try {
                     const imessageAdapter = createIMessageAdapter();
-                    await imessageAdapter.connect();
-                    broker.addAdapter(imessageAdapter);
+                    const abortConnect = () => {
+                        void imessageAdapter.disconnect().catch(() => undefined);
+                    };
+                    signal?.addEventListener("abort", abortConnect, { once: true });
+                    try {
+                        await imessageAdapter.connect();
+                        signal?.throwIfAborted();
+                        broker.addAdapter(imessageAdapter);
+                    }
+                    finally {
+                        signal?.removeEventListener("abort", abortConnect);
+                    }
                     if (environment.blockers.length > 0) {
                         ctx.ui.notify(`iMessage send-first mode enabled — ${readinessSummary}`, "warning");
                         brokerRuntime.logActivity({
@@ -1173,11 +1360,13 @@ export default function (pi) {
                 }
             }
         }
+        signal?.throwIfAborted();
         broker.server.setOutboundMessageAdapters?.(broker.adapters);
         brokerRole = "broker";
         pinetEnabled = true;
         desiredAgentStatus = "idle";
         currentRuntimeMode = "broker";
+        await toolRegistrationRuntime.sync(pi, currentRuntimeMode);
         if (recoveredBrokerMessages > 0 || releasedBrokerClaims > 0) {
             const recoveredTargetedDetail = recoveredTargetedBacklogCount > 0
                 ? ` including ${recoveredTargetedBacklogCount} recovered targeted backlog item${recoveredTargetedBacklogCount === 1 ? "" : "s"}`
@@ -1185,7 +1374,6 @@ export default function (pi) {
             ctx.ui.notify(`Pinet broker recovered ${recoveredBrokerMessages} pending message${recoveredBrokerMessages === 1 ? "" : "s"}${recoveredTargetedDetail} and released ${releasedBrokerClaims} broker-owned thread claim${releasedBrokerClaims === 1 ? "" : "s"}`, "info");
         }
         brokerRuntime.startObservability(ctx);
-        setExtStatus(ctx, "ok");
         brokerRuntime.logActivity({
             kind: "broker_started",
             level: "actions",
@@ -1233,6 +1421,11 @@ export default function (pi) {
         },
         getAgentMetadata,
         applyRegistrationIdentity,
+        onRegistrationIdentityApplied: async () => {
+            if (currentRuntimeMode === "follower") {
+                await toolRegistrationRuntime.sync(pi, currentRuntimeMode);
+            }
+        },
         persistState,
         updateBadge,
         maybeDrainInboxIfIdle,
@@ -1240,6 +1433,7 @@ export default function (pi) {
         deferControlAck: deferFollowerControlAck,
         runRemoteControl,
         deliverFollowUpMessage,
+        deliverSteeringMessage,
         setExtStatus,
         getRuntimeDiagnostic: () => followerRuntimeDiagnostic,
         setRuntimeDiagnostic: (diagnostic) => {
@@ -1292,7 +1486,15 @@ export default function (pi) {
             lastBrokerControlPlaneHomeTabRefreshAt: () => brokerRuntime.getLastHomeTabRefreshAt(),
             lastBrokerControlPlaneHomeTabError: () => brokerRuntime.getLastHomeTabError(),
             subtreeBrokerStatus: () => subtreeBrokerRuntime.getStatus(),
+            inspectGlobalBroker: async () => {
+                const lock = inspectBrokerLock();
+                if (lock.state !== "alive") {
+                    return { lock, probe: null };
+                }
+                return { lock, probe: await probeBrokerSocket() };
+            },
             getPinetRegistrationBlockReason: pinetRegistrationGate.getBlockReason,
+            replaceGlobalBroker: async () => replaceBrokerOwner({ meshSecret: resolveLocalMeshSecretValue() }),
             connectAsBroker: (ctx) => transitionToRuntimeMode(ctx, "broker"),
             connectAsFollower: (ctx) => transitionToRuntimeMode(ctx, "follower"),
             reloadPinetRuntime,
@@ -1302,21 +1504,27 @@ export default function (pi) {
             spawnSubtreeWorker: (ctx, input) => subtreeBrokerRuntime.spawnWorker(ctx, input),
             sendPinetAgentMessage,
             signalAgentFree,
-            applyLocalAgentIdentity,
+            applyLocalAgentIdentity: async (name, emoji, personality) => {
+                applyLocalAgentIdentity(name, emoji, personality);
+                await toolRegistrationRuntime.sync(pi, currentRuntimeMode);
+            },
             setExtStatus,
             setExtCtx: sessionUiRuntime.setExtCtx,
         },
     });
     commandRegistrationRuntime.register(pi);
-    async function connectAsFollower(ctx) {
+    async function connectAsFollower(ctx, signal) {
+        signal?.throwIfAborted();
         pinetRegistrationGate.assertCanRegister();
-        const clientRef = await followerRuntime.connect(ctx);
+        const clientRef = await followerRuntime.connect(ctx, signal);
+        signal?.throwIfAborted();
         brokerClient = clientRef;
         followerRuntimeDiagnostic = null;
         brokerRole = "follower";
         pinetEnabled = true;
         desiredAgentStatus = "idle";
         currentRuntimeMode = "follower";
+        await toolRegistrationRuntime.sync(pi, currentRuntimeMode);
         setExtStatus(ctx, "ok");
     }
     async function disconnectFollower(ctx, options = {}) {
@@ -1326,6 +1534,7 @@ export default function (pi) {
         brokerRole = null;
         pinetEnabled = false;
         currentRuntimeMode = "off";
+        await toolRegistrationRuntime.sync(pi, currentRuntimeMode);
         if (!options.preserveErrorState) {
             followerRuntimeDiagnostic = null;
             setExtStatus(ctx, "off");
@@ -1334,6 +1543,8 @@ export default function (pi) {
     }
     // ─── Lifecycle ──────────────────────────────────────
     pi.on("session_start", async (_event, ctx) => {
+        await cancelPendingStartup();
+        compactionGate.reset();
         singlePlayerRuntime.resetShutdownState();
         slackRequestRuntime.reset();
         resetRemoteControlState();
@@ -1346,43 +1557,65 @@ export default function (pi) {
             console.log("[slack-bridge] detected local subagent context; skipping Pinet registration");
             currentRuntimeMode = "off";
             setExtStatus(ctx, "off");
+            await toolRegistrationRuntime.sync(pi, currentRuntimeMode);
             return;
         }
         refreshSettings();
         maybeWarnSlackUserAccess(ctx);
         const startupMode = resolveSlackBridgeStartupRuntimeMode(settings, {
-            brokerSocketExists: fs.existsSync(DEFAULT_SOCKET_PATH),
+            brokerSocketExists: fs.existsSync(resolveBrokerSocketPath()),
             brokerManagedFollowerLaunch: isBrokerManagedFollowerLaunch(),
         });
-        try {
+        if (startupMode === "off") {
             await transitionToRuntimeMode(ctx, startupMode);
-            if (startupMode === "single") {
-                maybeWarnSlackGuardrailPosture(ctx);
-                console.log("[slack-bridge] runtime mode: single");
+            return;
+        }
+        await toolRegistrationRuntime.sync(pi, "off");
+        setExtStatus(ctx, "reconnecting");
+        const controller = new AbortController();
+        const startupPromise = (async () => {
+            try {
+                await runRuntimeModeTransition(ctx, startupMode, controller.signal);
+                if (startupMode === "single") {
+                    maybeWarnSlackGuardrailPosture(ctx);
+                }
+                console.log(`[slack-bridge] runtime mode: ${startupMode}`);
             }
-            else if (startupMode === "follower") {
-                console.log("[slack-bridge] runtime mode: follower");
+            catch (error) {
+                const cancelled = controller.signal.aborted || isAbortError(error);
+                if (!cancelled) {
+                    console.error(`[slack-bridge] runtime start (${startupMode}) failed: ${msg(error)}`);
+                }
+                await runPinetLifecycle(() => stopPinetRuntime(ctx, { releaseIdentity: !cancelled })).catch((cleanupError) => {
+                    console.error(`[slack-bridge] runtime cleanup failed: ${msg(cleanupError)}`);
+                });
+                slackRequestRuntime.reset();
+                singlePlayerRuntime.resetShutdownState();
             }
-            else if (startupMode === "broker") {
-                console.log("[slack-bridge] runtime mode: broker");
+            finally {
+                if (pendingStartup?.controller === controller)
+                    pendingStartup = null;
             }
-        }
-        catch (err) {
-            console.error(`[slack-bridge] runtime start (${startupMode}) failed: ${msg(err)}`);
-            currentRuntimeMode = "off";
-            setExtStatus(ctx, "off");
-        }
+        })().catch((error) => {
+            console.error(`[slack-bridge] background runtime start failed: ${msg(error)}`);
+        });
+        pendingStartup = { controller, promise: startupPromise };
     });
     // ─── Agent event wiring ──────────────────────────────
     agentEventRuntime.register(pi);
-    pi.on("session_compact", async (_event, ctx) => {
-        maybeDrainInboxIfIdle(ctx);
+    pi.on("session_before_compact", (event) => {
+        compactionGate.begin(event.signal);
+    });
+    pi.on("session_compact", () => {
+        compactionGate.end();
     });
     pi.on("session_shutdown", async (_event, ctx) => {
+        compactionGate.reset();
         resetRemoteControlState();
         resetPendingRemoteControlAcks();
         sessionUiRuntime.cleanupForSessionShutdown();
-        await stopPinetRuntime(ctx, { releaseIdentity: true });
+        await cancelPendingStartup();
+        await runPinetLifecycle(() => stopPinetRuntime(ctx, { releaseIdentity: true }));
         pinetRegistrationGate.reset();
     });
 }