@pinet/slack-bridge 0.2.2 → 0.2.6

package/dist/broker/socket-server.js

@@ -8,7 +8,7 @@ import { dispatchDirectAgentMessage } from "./agent-messaging.js";
 import { sendBrokerMessage } from "./message-send.js";
 import { assertLoopbackTcpHost } from "./raw-tcp-loopback.js";
 import { summarizePinetStableId } from "../pinet-session-formatting.js";
-import { RPC_PARSE_ERROR, RPC_INVALID_REQUEST, RPC_METHOD_NOT_FOUND, RPC_INVALID_PARAMS, RPC_INTERNAL_ERROR, RPC_AUTH_REQUIRED, RPC_AGENT_NAME_CONFLICT, RPC_AGENT_STABLE_ID_CONFLICT, } from "./types.js";
+import { RPC_PARSE_ERROR, RPC_INVALID_REQUEST, RPC_METHOD_NOT_FOUND, RPC_INVALID_PARAMS, RPC_INTERNAL_ERROR, RPC_AUTH_REQUIRED, RPC_AGENT_NAME_CONFLICT, RPC_AGENT_STABLE_ID_CONFLICT, RPC_AGENT_WAKE_FENCE_REJECTED, } from "./types.js";
 export const DEFAULT_HEARTBEAT_TIMEOUT_MS = 15_000;
 export const DEFAULT_PRUNE_INTERVAL_MS = 5_000;
 export const DEFAULT_AUTH_TIMEOUT_MS = 2_000;
@@ -79,6 +79,7 @@ export class BrokerSocketServer {
     agentStatusChangeCallback = null;
     outboundMessageAdapters = [];
     agentRegistrationResolver = null;
+    adminShutdownHandler = null;
     constructor(db, target, options = {}) {
         this.db = db;
         this.router = new MessageRouter(db);
@@ -199,6 +200,24 @@ export class BrokerSocketServer {
     setAgentRegistrationResolver(resolver) {
         this.agentRegistrationResolver = resolver;
     }
+    disconnectAgentConnections(agentId) {
+        for (const [socket, state] of this.connections) {
+            if (state.agentId !== agentId)
+                continue;
+            state.agentId = null;
+            socket.destroy();
+        }
+    }
+    /**
+     * Register a handler invoked when an authenticated local client requests a
+     * graceful broker shutdown via the `admin.shutdown` RPC (used by
+     * `/pinet start replace` to take over a broker whose controlling session
+     * was lost). When no handler is wired, the RPC reports method-not-found so
+     * callers treat the broker as not supporting remote shutdown.
+     */
+    setAdminShutdownHandler(handler) {
+        this.adminShutdownHandler = handler;
+    }
     setOutboundMessageAdapters(adapters) {
         this.outboundMessageAdapters = adapters;
     }
@@ -386,6 +405,8 @@ export class BrokerSocketServer {
                     return this.handleScheduleCreate(req, state);
                 case "status.update":
                     return this.handleStatusUpdate(req, state);
+                case "admin.shutdown":
+                    return this.handleAdminShutdown(req);
                 case "adapter.capability":
                     return await this.handleAdapterCapability(req, state);
                 case "slack.proxy":
@@ -420,15 +441,147 @@ export class BrokerSocketServer {
         this.clearAuthTimer(state);
         return rpcOk(req.id, { ok: true });
     }
+    /**
+     * Enforce the accepted-generation wake fence for durable hibernation
+     * identities. Returns a rejection response when the fence fails; on success
+     * for a hibernation identity it accepts the generation and binds this
+     * connection to the revived agent id. Ordinary registration returns no
+     * rejection and leaves state untouched.
+     */
+    enforceWakeFence(req, stableId, fence) {
+        const { wakeLeaseId, fenceToken, reservedGeneration, reservationNonce } = fence;
+        const hasFence = wakeLeaseId !== undefined ||
+            fenceToken !== undefined ||
+            reservedGeneration !== undefined ||
+            reservationNonce !== undefined;
+        // A wake fence is only meaningful for a specific durable stable identity.
+        // Compute `hasFence` BEFORE the ordinary-registration fast path so a runtime
+        // cannot omit `stableId`, present its broker-issued fence, and register as a
+        // fresh authorized agent that skipped fence enforcement entirely (a malformed
+        // wake runtime could otherwise do exactly this during the wake window). A
+        // fence with no stableId has no identity to revive → reject fail-closed; only
+        // a fence-free, stableId-less registration is a legitimate ordinary one.
+        if (!stableId) {
+            if (hasFence) {
+                return {
+                    rejection: rpcError(req.id, RPC_AGENT_WAKE_FENCE_REJECTED, "Wake fence presented without a stableId; no hibernated identity to revive.", { code: "WAKE_FENCE_REJECTED", reason: "fence_without_stable_id", retryable: false }),
+                };
+            }
+            return { rejection: null };
+        }
+        const existing = this.db.getAgentByStableId(stableId);
+        const lifecycleState = existing?.lifecycleState;
+        const durableHibernation = lifecycleState === "hibernated" || lifecycleState === "waking";
+        // Non-live lifecycle states that must NEVER accept a self-registration into
+        // their stable identity. `hibernating` is mid-teardown: the old runtime may
+        // still be alive and only a broker-driven wake (from `hibernated`) may revive
+        // it, so a fresh registration during the teardown window must not bind the
+        // socket. `reap-candidate` is quarantined pending manual review and
+        // `terminated` is a closed identity — neither may silently reconnect and
+        // regain broker RPC access. Fail closed regardless of any presented fence.
+        const registrationBlocked = lifecycleState === "hibernating" ||
+            lifecycleState === "reap-candidate" ||
+            lifecycleState === "terminated";
+        if (registrationBlocked) {
+            return {
+                rejection: rpcError(req.id, RPC_AGENT_WAKE_FENCE_REJECTED, `Registration into a ${lifecycleState} identity is not permitted; this stableId is not awaiting wake.`, {
+                    code: "WAKE_FENCE_REJECTED",
+                    reason: `state_${lifecycleState}`,
+                    retryable: false,
+                }),
+            };
+        }
+        if (!durableHibernation) {
+            // Ordinary registration. A wake fence presented with no hibernation
+            // identity to revive is a stale/mismatched wake — reject fail-closed
+            // rather than silently registering a fresh row.
+            if (hasFence) {
+                // EXCEPTION — idempotent crash-recovery replay. If the durable row is now
+                // `live` with the generation ALREADY advanced to the reserved generation,
+                // and an exact acceptance receipt matches the presented single-use fence,
+                // this is a runtime whose acceptance committed but whose register RPC
+                // response was lost to a broker crash (recovery then promoted the
+                // accepted-but-stranded wake to `live`). Re-bind it idempotently WITHOUT
+                // accepting a new generation, rather than reject a legitimate,
+                // already-accepted runtime and strand it. Fail-closed: only an EXACT
+                // receipt match on a `live` identity qualifies; the receipt is cleared by
+                // the next wake reservation, so a stale fence cannot rebind during a fresh
+                // wake window. A live duplicate connection is already rejected earlier by
+                // `findLiveStableIdConflict`, so this never double-binds a running runtime.
+                if (lifecycleState === "live" &&
+                    existing &&
+                    wakeLeaseId !== undefined &&
+                    fenceToken !== undefined &&
+                    reservedGeneration !== undefined &&
+                    reservationNonce !== undefined) {
+                    const receipt = this.db.getAgentWakeAcceptanceReceipt(existing.id);
+                    if (receipt &&
+                        receipt.stableId === stableId &&
+                        receipt.wakeLeaseId === wakeLeaseId &&
+                        receipt.fenceToken === fenceToken &&
+                        receipt.reservedGeneration === reservedGeneration &&
+                        receipt.reservationNonce === reservationNonce &&
+                        existing.runtimeGeneration === reservedGeneration) {
+                        return { rejection: null, rebind: { agentId: existing.id } };
+                    }
+                }
+                return {
+                    rejection: rpcError(req.id, RPC_AGENT_WAKE_FENCE_REJECTED, "Wake fence presented but no hibernated identity is awaiting wake for this stableId.", { code: "WAKE_FENCE_REJECTED", reason: "no_hibernation_identity", retryable: false }),
+                };
+            }
+            return { rejection: null };
+        }
+        if (wakeLeaseId === undefined ||
+            fenceToken === undefined ||
+            reservedGeneration === undefined ||
+            reservationNonce === undefined) {
+            return {
+                rejection: rpcError(req.id, RPC_AGENT_WAKE_FENCE_REJECTED, "Registration into a hibernated identity requires a broker-issued wake lease, fence token, runtime generation, and reservation nonce.", { code: "WAKE_FENCE_REJECTED", reason: "missing_fence", retryable: false }),
+            };
+        }
+        // Preflight only: validate the fence WITHOUT advancing the generation or
+        // consuming the reservation. The generation is accepted in handleRegister
+        // *after* the agent registration commits, so a later name conflict or
+        // registration failure can never advance the generation (and thus falsely
+        // signal the orchestrator that a runtime registered) for a runtime that did
+        // not actually register. Registration is synchronous, so a passing
+        // preflight is immediately followed by acceptance with no interleaving.
+        const accept = {
+            agentId: existing.id,
+            wakeLeaseId,
+            fenceToken,
+            reservedGeneration,
+            reservationNonce,
+        };
+        const preflight = this.db.checkRuntimeGenerationAcceptable(accept);
+        if (!preflight.accepted) {
+            return {
+                rejection: rpcError(req.id, RPC_AGENT_WAKE_FENCE_REJECTED, `Wake fence rejected: ${preflight.reason}.`, { code: "WAKE_FENCE_REJECTED", reason: preflight.reason, retryable: false }),
+            };
+        }
+        return { rejection: null, revive: { agentId: existing.id, accept } };
+    }
     handleRegister(req, state, socket) {
         const params = req.params ?? {};
         const requestedName = typeof params.name === "string" ? params.name.trim() : "";
         const requestedEmoji = typeof params.emoji === "string" ? params.emoji : "";
         const pid = typeof params.pid === "number" ? params.pid : 0;
         const stableId = typeof params.stableId === "string" ? params.stableId : undefined;
-        const metadata = params.metadata && typeof params.metadata === "object"
+        const rawMetadata = params.metadata && typeof params.metadata === "object"
             ? params.metadata
             : undefined;
+        const legacyTmuxSession = typeof rawMetadata?.tmuxSession === "string" ? rawMetadata.tmuxSession.trim() : "";
+        const launchSource = typeof rawMetadata?.launchSource === "string" ? rawMetadata.launchSource.trim() : "";
+        const explicitlyHerdr = rawMetadata?.runtimeKind === "herdr" ||
+            launchSource === "broker-herdr" ||
+            launchSource === "subtree-broker-herdr";
+        const metadata = legacyTmuxSession && !explicitlyHerdr && typeof rawMetadata?.runtimeLocator !== "string"
+            ? {
+                ...rawMetadata,
+                runtimeKind: "tmux",
+                runtimeLocator: legacyTmuxSession,
+            }
+            : rawMetadata;
         if (stableId) {
             const liveStableIdConflict = this.findLiveStableIdConflict(stableId, socket);
             if (liveStableIdConflict) {
@@ -440,7 +593,32 @@ export class BrokerSocketServer {
                 });
             }
         }
-        const candidateId = state.agentId ?? crypto.randomUUID();
+        // Fenced revival of a durable hibernation identity. A hibernated/waking
+        // agent row has no live process and may only be revived by a
+        // broker-initiated wake presenting its exact wake lease, fence token, and
+        // reserved runtime generation. Ordinary (non-wake) registration is
+        // unaffected; a wake fence presented against a non-hibernation identity is
+        // treated as stale and rejected. Fails closed: on any mismatch the socket
+        // is not bound and the row is not revived.
+        const wakeFence = this.enforceWakeFence(req, stableId, {
+            wakeLeaseId: typeof params.wakeLeaseId === "string" ? params.wakeLeaseId : undefined,
+            fenceToken: typeof params.fenceToken === "number" ? params.fenceToken : undefined,
+            reservedGeneration: typeof params.runtimeGeneration === "number" ? params.runtimeGeneration : undefined,
+            reservationNonce: typeof params.reservationNonce === "string" ? params.reservationNonce : undefined,
+        });
+        if (wakeFence.rejection)
+            return wakeFence.rejection;
+        // A fenced revival targets the existing hibernated row so registerAgent
+        // updates it (preserving lifecycle + generation) instead of minting a new
+        // one. state.agentId is bound only after full success below, so a failure
+        // path never leaves this connection authorized as the revived agent. An
+        // idempotent crash-recovery rebind likewise targets the existing (now `live`)
+        // row: the plain-register branch below updates its pid/metadata and binds the
+        // socket WITHOUT accepting a new generation (already accepted).
+        const candidateId = wakeFence.revive?.agentId ??
+            wakeFence.rebind?.agentId ??
+            state.agentId ??
+            crypto.randomUUID();
         const resolved = this.agentRegistrationResolver?.({
             agentId: candidateId,
             name: requestedName,
@@ -469,7 +647,35 @@ export class BrokerSocketServer {
                 });
             }
         }
-        const agent = this.db.registerAgent(candidateId, finalName, finalEmoji, pid, finalMetadata, stableId);
+        let agent;
+        if (wakeFence.revive) {
+            // Fenced revival: perform the registration mutation AND accept the reserved
+            // generation in ONE broker transaction. If acceptance fails (e.g. the wake
+            // lease expires in the sub-ms window after the preflight), the whole
+            // registration mutation rolls back and the socket is refused and unbound —
+            // the durable row is never left with a mutated pid/metadata/connectivity.
+            // The orchestrator's registration wait then times out and quarantines
+            // rather than promoting a half-revived identity to live.
+            const revived = this.db.registerAgentWithGenerationAcceptance({
+                registration: {
+                    id: candidateId,
+                    name: finalName,
+                    emoji: finalEmoji,
+                    pid,
+                    metadata: finalMetadata,
+                    stableId,
+                },
+                accept: wakeFence.revive.accept,
+            });
+            if (!revived.agent || !revived.acceptance.accepted) {
+                const reason = revived.acceptance.accepted ? "unknown" : revived.acceptance.reason;
+                return rpcError(req.id, RPC_AGENT_WAKE_FENCE_REJECTED, `Wake fence rejected during revival: ${reason}.`, { code: "WAKE_FENCE_REJECTED", reason, retryable: false });
+            }
+            agent = revived.agent;
+        }
+        else {
+            agent = this.db.registerAgent(candidateId, finalName, finalEmoji, pid, finalMetadata, stableId);
+        }
         this.disconnectDuplicateConnections(agent.id, socket);
         state.agentId = agent.id;
         return rpcOk(req.id, {
@@ -713,6 +919,9 @@ export class BrokerSocketServer {
             ...(typeof params.threadId === "string" ? { threadId: params.threadId } : {}),
             ...(typeof params.repo === "string" ? { repo: params.repo } : {}),
             ...(typeof params.worktreePath === "string" ? { worktreePath: params.worktreePath } : {}),
+            ...(typeof params.runtimeLocator === "string"
+                ? { runtimeLocator: params.runtimeLocator }
+                : {}),
             ...(typeof params.tmuxSession === "string" ? { tmuxSession: params.tmuxSession } : {}),
             ...(typeof params.since === "string" ? { since: params.since } : {}),
             ...(typeof params.until === "string" ? { until: params.until } : {}),
@@ -1076,8 +1285,37 @@ export class BrokerSocketServer {
         }
         return rpcOk(req.id, { ok: true });
     }
+    // ─── Admin shutdown handler ───────────────────────────
+    /**
+     * Graceful remote shutdown. Requires authentication (enforced by the
+     * generic auth gate). Responds first, then invokes the wired handler on the
+     * next tick so the requester receives the acknowledgement before the broker
+     * tears down its socket.
+     */
+    handleAdminShutdown(req) {
+        const handler = this.adminShutdownHandler;
+        if (!handler) {
+            return rpcError(req.id, RPC_METHOD_NOT_FOUND, "This broker does not support remote shutdown.");
+        }
+        setImmediate(() => {
+            void Promise.resolve()
+                .then(() => handler())
+                .catch(() => {
+                /* best effort — the requester falls back to fenced termination */
+            });
+        });
+        return rpcOk(req.id, { ok: true, shuttingDown: true });
+    }
     // ─── Adapter capability handler ───────────────────────
     async handleAdapterCapability(req, state) {
+        // #855: adapter.capability must be identity-bound so the broker can
+        // enforce thread ownership. Unregistered callers cannot own or claim
+        // threads, so they must not be able to invoke outbound-side capabilities
+        // (chat.postMessage in particular) that would race a first-responder
+        // claim or take over a thread already owned by another agent.
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
         const params = req.params ?? {};
         const adapterName = typeof params.adapter === "string"
             ? params.adapter.trim()
@@ -1097,6 +1335,12 @@ export class BrokerSocketServer {
         return await this.dispatchAdapterCapability(req.id, adapterName, capability, capabilityParams, state);
     }
     async handleLegacySlackProxy(req, state) {
+        // #855: legacy slack.proxy is a compatibility wrapper over
+        // adapter.capability and must enforce the same registration bar so
+        // unregistered callers cannot bypass thread ownership via chat.postMessage.
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
         const params = req.params ?? {};
         const method = typeof params.method === "string" ? params.method.trim() : "";
         if (!method) {
@@ -1112,6 +1356,15 @@ export class BrokerSocketServer {
         if (!adapter?.invokeCapability) {
             return rpcError(id, RPC_METHOD_NOT_FOUND, `Adapter ${adapterName} does not implement capability ${capability}`);
         }
+        // #855: refuse cross-owner Slack chat.postMessage before hitting Slack.
+        // Without this pre-check the adapter posts first and the broker races a
+        // first-responder-wins claim via effects.claimThread — letting an
+        // unauthorized follower take over a thread already owned by another
+        // agent simply by winning the send.
+        const ownershipError = this.checkAdapterCapabilityThreadOwnership(adapterName, capability, capabilityParams, state.agentId);
+        if (ownershipError) {
+            return rpcError(id, RPC_INVALID_PARAMS, `${errorPrefix}: ${ownershipError}`);
+        }
         try {
             const response = await adapter.invokeCapability({ capability, params: capabilityParams });
             this.applyAdapterCapabilityEffects(adapterName, response, state);
@@ -1122,6 +1375,36 @@ export class BrokerSocketServer {
             return rpcError(id, RPC_INTERNAL_ERROR, `${errorPrefix}: ${message}`);
         }
     }
+    checkAdapterCapabilityThreadOwnership(adapterName, capability, capabilityParams, callerAgentId) {
+        if (adapterName !== "slack")
+            return null;
+        if (capability !== "api.call")
+            return null;
+        const method = typeof capabilityParams.method === "string" ? capabilityParams.method.trim() : "";
+        if (method !== "chat.postMessage")
+            return null;
+        const inner = capabilityParams.params &&
+            typeof capabilityParams.params === "object" &&
+            !Array.isArray(capabilityParams.params)
+            ? capabilityParams.params
+            : {};
+        const threadTs = typeof inner.thread_ts === "string" ? inner.thread_ts.trim() : "";
+        if (!threadTs)
+            return null;
+        // Defense in depth (#855): even if a future call path forgot the
+        // registration guard on the handler, refuse threaded chat.postMessage
+        // for unregistered callers here — they cannot own a Slack thread and
+        // must not be able to post into one.
+        if (!callerAgentId) {
+            return `Slack thread ${threadTs}: refusing threaded chat.postMessage from an unregistered caller`;
+        }
+        const thread = this.db.getThread(threadTs);
+        if (!thread?.ownerAgent)
+            return null;
+        if (thread.ownerAgent === callerAgentId)
+            return null;
+        return `Slack thread ${threadTs} is already owned by another agent; refusing cross-owner chat.postMessage`;
+    }
     applyAdapterCapabilityEffects(adapterName, response, state) {
         if (!state.agentId)
             return;

package/dist/broker-delivery.d.ts

@@ -8,3 +8,4 @@ export declare function isBrokerInboxIdTracked(state: BrokerDeliveryState, inbox
 export declare function queueBrokerInboxIds(state: BrokerDeliveryState, inboxIds: Iterable<number>): void;
 export declare function markBrokerInboxIdsHandled(state: BrokerDeliveryState, inboxIds: Iterable<number>): void;
 export declare function getBrokerInboxIds(messages: InboxMessage[]): number[];
+export declare function getSubtreeInboxIds(messages: InboxMessage[]): number[];

package/dist/broker-delivery.js

@@ -21,6 +21,15 @@ export function markBrokerInboxIdsHandled(state, inboxIds) {
 }
 export function getBrokerInboxIds(messages) {
     return [
-        ...new Set(messages.flatMap((message) => (message.brokerInboxId ? [message.brokerInboxId] : []))),
+        ...new Set(messages.flatMap((message) => message.brokerInboxId && message.brokerInboxOrigin !== "subtree"
+            ? [message.brokerInboxId]
+            : [])),
+    ];
+}
+export function getSubtreeInboxIds(messages) {
+    return [
+        ...new Set(messages.flatMap((message) => message.brokerInboxId && message.brokerInboxOrigin === "subtree"
+            ? [message.brokerInboxId]
+            : [])),
     ];
 }

package/dist/broker-runtime.d.ts

@@ -23,7 +23,7 @@ export interface BrokerRuntimeDeps {
     getActiveSkinTheme: () => string | null;
     setActiveSkinTheme: (theme: string) => void;
     setAgentOwnerToken: (ownerToken: string) => void;
-    getAgentMetadata: (role: "broker" | "worker") => Promise<Record<string, unknown>>;
+    getAgentMetadata: (role: "broker" | "worker", signal?: AbortSignal) => Promise<Record<string, unknown>>;
     applyLocalAgentIdentity: (name: string, emoji: string, personality: string | null) => void;
     buildSkinMetadata: (metadata: Record<string, unknown> | undefined, personality: string, statusVocabulary?: PinetSkinStatusVocabulary) => Record<string, unknown>;
     getMeshRoleFromMetadata: (metadata: Record<string, unknown> | undefined, fallback?: "broker" | "worker") => "broker" | "worker";
@@ -37,6 +37,7 @@ export interface BrokerRuntimeDeps {
     pushInboxMessages: (messages: InboxMessage[]) => void;
     updateBadge: () => void;
     maybeDrainInboxIfIdle: (ctx: ExtensionContext) => boolean;
+    deliverSteeringMessage: (text: string, ctx: ExtensionContext) => boolean;
     requestRemoteControl: (command: PinetControlCommand, ctx: ExtensionContext) => PinetRemoteControlRequestResult;
     deferControlAck: (command: PinetControlCommand, inboxId: number) => void;
     runRemoteControl: (command: PinetControlCommand, ctx: ExtensionContext) => void;
@@ -62,10 +63,21 @@ export interface BrokerRuntimeDeps {
     buildControlPlaneDashboardSnapshot: (input: Record<string, unknown>) => BrokerControlPlaneDashboardSnapshot;
     buildCurrentDashboardSnapshot: (openedAt?: string) => Promise<BrokerControlPlaneDashboardSnapshot | null>;
     createAdapterBindings: readonly PinetRuntimeAdapterFactory[];
+    /**
+     * Invoked when an authenticated local client asks this broker to shut down
+     * gracefully (`admin.shutdown`, used by `/pinet start replace`). The
+     * implementation should stop the Pinet runtime in the owning session and
+     * notify its operator; the session itself stays alive.
+     */
+    onAdminShutdownRequested: (ctx: ExtensionContext) => Promise<void>;
 }
 export declare function resolveConfiguredBrokerSkinTheme(settings: SlackBridgeSettings): string;
 export interface BrokerRuntime {
-    connect: (ctx: ExtensionContext) => Promise<BrokerRuntimeConnectResult>;
+    connect: (ctx: ExtensionContext, signal?: AbortSignal) => Promise<BrokerRuntimeConnectResult>;
+    reloadAdapters: (ctx: ExtensionContext) => Promise<{
+        botUserId: string | null;
+    }>;
+    canReloadInPlace: () => boolean;
     disconnect: (options?: {
         releaseIdentity?: boolean;
     }) => Promise<void>;

package/dist/broker-runtime.js

@@ -1,5 +1,7 @@
-import { buildPinetOwnerToken, buildPinetSkinAssignment, DEFAULT_PINET_SKIN_THEME, normalizePinetSkinTheme, resolvePinetMeshAuth, syncBrokerInboxEntries, } from "./helpers.js";
+import * as crypto from "node:crypto";
+import { buildPinetOwnerToken, buildPinetSkinAssignment, DEFAULT_PINET_SKIN_THEME, formatPinetSteeringMessage, normalizePinetSkinTheme, resolvePinetMeshAuth, syncBrokerInboxEntries, } from "./helpers.js";
 import { startBroker } from "./broker/index.js";
+import { readMeshSecret } from "./broker/auth.js";
 import { DEFAULT_HEARTBEAT_TIMEOUT_MS } from "./broker/socket-server.js";
 import { MessageRouter } from "./broker/router.js";
 import { DEFAULT_BROKER_MAINTENANCE_INTERVAL_MS, DEFAULT_BUSY_ASSIGNMENT_AGE_MS, runBrokerMaintenancePass, } from "./broker/maintenance.js";
@@ -14,6 +16,22 @@ function normalizeOptionalSetting(value) {
     const trimmed = value?.trim();
     return trimmed && trimmed.length > 0 ? trimmed : null;
 }
+function buildBrokerInPlaceSettingsSignature(settings) {
+    const meshAuth = resolvePinetMeshAuth(settings);
+    const effectiveMeshSecret = meshAuth.meshSecret
+        ? meshAuth.meshSecret
+        : meshAuth.meshSecretPath
+            ? readMeshSecret(meshAuth.meshSecretPath)
+            : null;
+    const meshSecretFingerprint = effectiveMeshSecret
+        ? crypto.createHash("sha256").update(effectiveMeshSecret).digest("hex")
+        : null;
+    return JSON.stringify({
+        meshSecretFingerprint,
+        meshSecretPath: meshAuth.meshSecretPath ?? null,
+        imessageEnabled: settings.imessage?.enabled ?? false,
+    });
+}
 export function resolveConfiguredBrokerSkinTheme(settings) {
     return normalizePinetSkinTheme(settings.skinTheme) ?? DEFAULT_PINET_SKIN_THEME;
 }
@@ -21,6 +39,8 @@ export function createBrokerRuntime(deps) {
     let activeBroker = null;
     let activeRouter = null;
     let activeSelfId = null;
+    let activeRuntimeAdapters = [];
+    let activeInPlaceSettingsSignature = null;
     let brokerHeartbeatTimer = null;
     let brokerMaintenanceTimer = null;
     let brokerScheduledWakeupTimer = null;
@@ -132,6 +152,20 @@ export function createBrokerRuntime(deps) {
         for (const command of commandsToStart) {
             deps.runRemoteControl(command, ctx);
         }
+        const steeredInboxIds = [];
+        for (const entry of synced.steeringEntries) {
+            try {
+                if (deps.deliverSteeringMessage(formatPinetSteeringMessage(entry), ctx)) {
+                    steeredInboxIds.push(entry.inboxId);
+                }
+            }
+            catch (error) {
+                ctx.ui.notify(`Pinet steering delivery failed: ${deps.formatError(error)}`, "error");
+            }
+        }
+        if (steeredInboxIds.length > 0) {
+            db.markDelivered(steeredInboxIds, agentId);
+        }
         if (synced.inboxMessages.length === 0) {
             return;
         }
@@ -303,12 +337,15 @@ export function createBrokerRuntime(deps) {
         activeBroker = null;
         activeRouter = null;
         activeSelfId = null;
+        activeRuntimeAdapters = [];
+        activeInPlaceSettingsSignature = null;
         lastBrokerMaintenance = null;
         lastBrokerMaintenanceSignature = "";
         resetBrokerDeliveryState(deps.deliveryState);
     }
     return {
-        async connect(ctx) {
+        async connect(ctx, signal) {
+            signal?.throwIfAborted();
             const settings = deps.getSettings();
             const meshAuth = resolvePinetMeshAuth(settings);
             const allowedUsers = deps.getAllowedUsers();
@@ -319,6 +356,7 @@ export function createBrokerRuntime(deps) {
             let selfId = null;
             activityLogContext = ctx;
             try {
+                signal?.throwIfAborted();
                 broker.db.setAllowedUsers(allowedUsers);
                 const router = new MessageRouter(broker.db);
                 const persistedBrokerStableId = normalizeOptionalSetting(broker.db.getSetting("pinet.brokerStableId")) ??
@@ -368,7 +406,9 @@ export function createBrokerRuntime(deps) {
                     role: "broker",
                     seed: brokerStableId,
                 });
-                const selfAgent = broker.db.registerAgent(ctx.sessionManager.getLeafId() ?? `broker-${process.pid}`, selfAssignment.name, selfAssignment.emoji, process.pid, deps.buildSkinMetadata(await deps.getAgentMetadata("broker"), selfAssignment.personality, selfAssignment.statusVocabulary), brokerStableId);
+                const agentMetadata = await deps.getAgentMetadata("broker", signal);
+                signal?.throwIfAborted();
+                const selfAgent = broker.db.registerAgent(ctx.sessionManager.getLeafId() ?? `broker-${process.pid}`, selfAssignment.name, selfAssignment.emoji, process.pid, deps.buildSkinMetadata(agentMetadata, selfAssignment.personality, selfAssignment.statusVocabulary), brokerStableId);
                 selfId = selfAgent.id;
                 deps.applyLocalAgentIdentity(selfAgent.name, selfAgent.emoji, selfAssignment.personality);
                 const brokerSelfId = selfId;
@@ -384,8 +424,12 @@ export function createBrokerRuntime(deps) {
                     onInbound: (message) => {
                         void deps.handleInboundMessage({ message, broker, router, selfId: brokerSelfId, ctx });
                     },
+                    signal,
                 });
+                signal?.throwIfAborted();
                 activeBroker = broker;
+                activeRuntimeAdapters = adapterBindings.map((binding) => binding.adapter);
+                activeInPlaceSettingsSignature = buildBrokerInPlaceSettingsSignature(settings);
                 activeRouter = router;
                 activeSelfId = brokerSelfId;
                 resetBrokerDeliveryState(deps.deliveryState);
@@ -404,6 +448,7 @@ export function createBrokerRuntime(deps) {
                     }
                     deps.onAgentStatusChange(ctx, changedAgentId, status);
                 });
+                broker.server.setAdminShutdownHandler(() => deps.onAdminShutdownRequested(ctx));
                 startBrokerHeartbeat();
                 startBrokerMaintenance(ctx);
                 startBrokerScheduledWakeups(ctx);
@@ -432,6 +477,8 @@ export function createBrokerRuntime(deps) {
                 activeBroker = null;
                 activeRouter = null;
                 activeSelfId = null;
+                activeRuntimeAdapters = [];
+                activeInPlaceSettingsSignature = null;
                 lastBrokerMaintenance = null;
                 lastBrokerMaintenanceSignature = "";
                 resetBrokerDeliveryState(deps.deliveryState);
@@ -439,6 +486,70 @@ export function createBrokerRuntime(deps) {
                 throw error;
             }
         },
+        async reloadAdapters(ctx) {
+            if (!activeBroker || !activeRouter || !activeSelfId) {
+                throw new Error("Pinet broker is not running.");
+            }
+            const broker = activeBroker;
+            const router = activeRouter;
+            const selfId = activeSelfId;
+            const bindings = await buildPinetRuntimeAdapterBindings(deps.createAdapterBindings, {
+                broker,
+                router,
+                selfId,
+                ctx,
+            });
+            const nextAdapters = bindings.map((binding) => binding.adapter);
+            const activeSkinTheme = resolveConfiguredBrokerSkinTheme(deps.getSettings());
+            const selfAssignment = buildPinetSkinAssignment({
+                theme: activeSkinTheme,
+                role: "broker",
+                seed: deps.getBrokerStableId(),
+            });
+            deps.setActiveSkinTheme(activeSkinTheme);
+            const selfMetadata = deps.buildSkinMetadata(await deps.getAgentMetadata("broker"), selfAssignment.personality, selfAssignment.statusVocabulary);
+            const previousRuntimeAdapters = activeRuntimeAdapters;
+            activeRuntimeAdapters = [];
+            await broker.removeAdapters(previousRuntimeAdapters);
+            broker.db.setAllowedUsers(deps.getAllowedUsers());
+            broker.db.setSetting("pinet.skinTheme", activeSkinTheme);
+            broker.db.updateAgentIdentity(selfId, {
+                name: selfAssignment.name,
+                emoji: selfAssignment.emoji,
+                metadata: selfMetadata,
+            });
+            deps.applyLocalAgentIdentity(selfAssignment.name, selfAssignment.emoji, selfAssignment.personality);
+            try {
+                const result = await connectPinetRuntimeAdapters({
+                    broker,
+                    bindings,
+                    onInbound: (message) => {
+                        void deps.handleInboundMessage({ message, broker, router, selfId, ctx });
+                    },
+                });
+                activeRuntimeAdapters = nextAdapters;
+                return result;
+            }
+            catch (error) {
+                try {
+                    await broker.removeAdapters(nextAdapters);
+                }
+                catch {
+                    /* preserve the adapter connection error */
+                }
+                throw error;
+            }
+        },
+        canReloadInPlace() {
+            try {
+                return (activeInPlaceSettingsSignature !== null &&
+                    activeInPlaceSettingsSignature === buildBrokerInPlaceSettingsSignature(deps.getSettings()));
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                throw new Error(`Cannot reload Pinet broker because the mesh secret could not be read: ${detail}. The existing broker remains running; restore the secret and retry /pinet start.`);
+            }
+        },
         async disconnect(options = {}) {
             await disconnect(options);
         },