@pinet/slack-bridge 0.2.4 → 0.2.7

package/README.md

@@ -263,6 +263,7 @@ Main commands:
 Coordinator commands:
 
 - `/pinet start` or `/pinet broker` - become the broker
+- `/pinet start replace` - take over a stale or stranded broker (graceful shutdown first, then a fenced SIGTERM fallback)
 - `/pinet follow` - become a follower
 - `/pinet unfollow` - disconnect from broker
 - `/pinet reload <agent>` - ask another agent to reload
@@ -380,6 +381,30 @@ If Pinet does not respond:
 4. Look in the log channel for errors
 5. Try `/pinet status` to check if Pinet is running
 
+### Stranded broker (lock held, controlling session lost)
+
+If `/pinet start` reports that another broker is already running but you no
+longer have that broker's Pi session (crash, laptop restart, stalled process):
+
+1. Run `/pinet status` from any session — it reports machine-wide broker lock
+   ownership and socket health even while disconnected.
+2. If the broker is healthy and you just want to participate, run
+   `/pinet follow`.
+3. If the broker is stranded (or you need the broker in this session), run
+   `/pinet start replace`. It asks the current broker to shut down gracefully
+   over the socket, falls back to a verified SIGTERM against the recorded lock
+   owner, and never escalates to SIGKILL.
+
+Two cases intentionally refuse automatic termination:
+
+- **Legacy locks** (written by older builds, PID-only): there is no recorded
+  process start identity, so a SIGTERM could hit an unrelated process that
+  reused the PID. Inspect the process manually (`ps -p <pid>`), terminate it
+  yourself if it is truly the stranded broker, then run `/pinet start`.
+- **Rejected shutdown**: a broker that responds but rejects the shutdown
+  request (usually a mesh secret mismatch) is alive, not stranded. Fix the
+  mesh secret configuration or stop that broker from its own session.
+
 ### Stalled agents
 
 If work gets stuck:
@@ -471,6 +496,6 @@ Prevent all modifications:
 
 ## Support
 
-- [GitHub repository](https://github.com/gugu91/extensions)
+- [GitHub repository](https://github.com/gugu91/pinet)
 - [Architecture documentation](../plans/)
 - Check the log channel in Slack for runtime issues

package/dist/activity-log.d.ts

@@ -18,6 +18,13 @@ export interface ActivityLogEntry {
 export interface LoggedActivityLogEntry extends ActivityLogEntry {
     timestamp: string;
 }
+export type ActivityLogSlackBlock = Record<string, unknown>;
+export interface ActivityLogPostMessageBody extends Record<string, unknown> {
+    channel: string;
+    text: string;
+    blocks: ActivityLogSlackBlock[];
+    thread_ts?: string;
+}
 export interface SlackActivityLoggerDeps {
     getBotToken: () => string | undefined;
     getLogChannel: () => string | undefined;
@@ -25,7 +32,7 @@ export interface SlackActivityLoggerDeps {
     getAgentName: () => string;
     getAgentEmoji: () => string;
     resolveChannel: (nameOrId: string) => Promise<string>;
-    slack: (method: string, token: string, body?: Record<string, unknown>) => Promise<SlackResult>;
+    slack: (method: string, token: string, body?: ActivityLogPostMessageBody) => Promise<SlackResult>;
     onError?: (error: unknown) => void;
     now?: () => Date;
     maxRecentEntries?: number;
@@ -34,10 +41,10 @@ export declare function normalizeActivityLogLevel(value: string | undefined): Ac
 export declare function shouldLogActivity(configuredLevel: ActivityLogLevel, eventLevel: ActivityLogLevel): boolean;
 export declare function redactSensitiveText(value: string): string;
 export declare function buildActivityLogText(agentName: string, agentEmoji: string, entry: LoggedActivityLogEntry): string;
-export declare function buildActivityLogBlocks(agentName: string, agentEmoji: string, entry: LoggedActivityLogEntry): Record<string, unknown>[];
+export declare function buildActivityLogBlocks(agentName: string, agentEmoji: string, entry: LoggedActivityLogEntry): ActivityLogSlackBlock[];
 export declare function buildActivityLogThreadHeader(agentName: string, agentEmoji: string, dateKey: string): {
     text: string;
-    blocks: Record<string, unknown>[];
+    blocks: ActivityLogSlackBlock[];
 };
 export declare function formatRecentActivityLogEntries(entries: ReadonlyArray<LoggedActivityLogEntry>): string;
 export declare class SlackActivityLogger {

package/dist/agent-event-runtime.d.ts

@@ -1,9 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgentCompletionRuntime } from "./agent-completion-runtime.js";
-import type { AgentPromptGuidance } from "./agent-prompt-guidance.js";
 import { type SlackToolPolicyRuntime, type SlackToolPolicyRuntimeDeps } from "./slack-tool-policy-runtime.js";
 export interface AgentEventRuntimeDeps extends SlackToolPolicyRuntimeDeps {
-    beforeAgentStart: AgentPromptGuidance["beforeAgentStart"];
     onCompletionAgentEnd: AgentCompletionRuntime["onAgentEnd"];
     setDeliverTrackedSlackFollowUpMessage: (deliver: SlackToolPolicyRuntime["deliverTrackedSlackFollowUpMessage"]) => void;
 }

package/dist/agent-event-runtime.js

@@ -18,7 +18,6 @@ export function createAgentEventRuntime(deps) {
         pi.on("turn_end", slackToolPolicyRuntime.onTurnEnd);
         pi.on("agent_end", slackToolPolicyRuntime.onAgentEnd);
         pi.on("tool_call", slackToolPolicyRuntime.onToolCall);
-        pi.on("before_agent_start", deps.beforeAgentStart);
         pi.on("agent_end", deps.onCompletionAgentEnd);
     }
     return {

package/dist/agent-prompt-guidance.d.ts

@@ -1,7 +1,4 @@
 import { type BrokerPromptLoadResult } from "./broker-prompt-loader.js";
-export interface BeforeAgentStartEvent {
-    systemPrompt: string;
-}
 export interface AgentPromptGuidanceDeps {
     getIdentityGuidelines: () => string[];
     getAgentName: () => string;
@@ -15,8 +12,6 @@ export interface AgentPromptGuidanceDeps {
     reportBrokerPromptDiagnostic?: (diagnostic: string) => void;
 }
 export interface AgentPromptGuidance {
-    beforeAgentStart: (event: BeforeAgentStartEvent) => Promise<{
-        systemPrompt: string;
-    }>;
+    buildPromptGuidelines: () => Promise<string[]>;
 }
 export declare function createAgentPromptGuidance(deps: AgentPromptGuidanceDeps): AgentPromptGuidance;

package/dist/agent-prompt-guidance.js

@@ -35,12 +35,7 @@ export function createAgentPromptGuidance(deps) {
         }
         return guidelines;
     }
-    async function beforeAgentStart(event) {
-        return {
-            systemPrompt: event.systemPrompt + "\n\n" + (await buildPromptGuidelines()).join("\n"),
-        };
-    }
     return {
-        beforeAgentStart,
+        buildPromptGuidelines,
     };
 }

package/dist/broker/adapters/slack.d.ts

@@ -1,4 +1,4 @@
-import { type ParsedAppHomeOpened, type ParsedSlashCommand, type ParsedThreadStarted } from "../../slack-access.js";
+import { type SlackSocketErrorSource, type ParsedAppHomeOpened, type ParsedSlashCommand, type ParsedThreadStarted } from "../../slack-access.js";
 import { type SlackIngressGuardSettings } from "../../helpers.js";
 import { type ReactionCommandSettings } from "../../reaction-triggers.js";
 import type { AdapterCapabilityRequest, AdapterCapabilityResult, InboundMessage, OutboundMessage, MessageAdapter } from "./types.js";
@@ -41,6 +41,9 @@ export interface SlackAdapterConfig {
     onAppHomeOpened?: (event: ParsedAppHomeOpened) => Promise<void> | void;
     /** Best-effort callback for Slack slash commands handled by the broker process. */
     onSlashCommand?: (event: ParsedSlashCommand) => Promise<string | null> | string | null;
+    onSocketOpen?: () => void;
+    onSocketReconnectScheduled?: () => void;
+    onSocketError?: (message: string, source: SlackSocketErrorSource) => void;
 }
 export declare const SLACK_THREAD_CACHE_MAX_SIZE = 5000;
 export declare const SLACK_THREAD_CACHE_TTL_MS: number;

package/dist/broker/adapters/slack.js

@@ -69,6 +69,8 @@ export class SlackAdapter {
             appToken: this.config.appToken,
             dedup: this.processedSocketDeliveries,
             abortAndWait: () => this.slackRequests.abortAndWait(),
+            onOpen: () => this.config.onSocketOpen?.(),
+            onReconnectScheduled: () => this.config.onSocketReconnectScheduled?.(),
             onThreadStarted: (event) => this.onThreadStarted(event),
             onThreadContextChanged: (event) => this.onContextChanged(event),
             onMessage: (event) => this.onMessage(event),
@@ -77,9 +79,9 @@ export class SlackAdapter {
             onAppHomeOpened: (event) => this.onAppHomeOpened(event),
             onInteractive: (event) => this.emitInteractiveInbound(event),
             onSlashCommand: (event) => this.onSlashCommand(event),
-            onError: (error) => {
+            onError: (error, source) => {
                 if (!isAbortError(error)) {
-                    console.error(`[slack-adapter] Socket Mode: ${errorMsg(error)}`);
+                    this.config.onSocketError?.(errorMsg(error), source);
                 }
             },
         });
@@ -88,14 +90,19 @@ export class SlackAdapter {
     }
     async disconnect() {
         this.shuttingDown = true;
-        await this.threadStatuses.clearAll();
-        const socketMode = this.socketMode;
-        this.socketMode = null;
-        if (socketMode) {
-            await socketMode.disconnect();
-            return;
+        try {
+            await this.threadStatuses.clearAll();
+        }
+        finally {
+            const socketMode = this.socketMode;
+            this.socketMode = null;
+            if (socketMode) {
+                await socketMode.disconnect();
+            }
+            else {
+                await this.slackRequests.abortAndWait();
+            }
         }
-        await this.slackRequests.abortAndWait();
     }
     onInbound(handler) {
         this.inboundHandler = handler;

package/dist/broker/client.d.ts

@@ -34,13 +34,23 @@ export interface ScheduledWakeupInfo {
 export type { PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput, };
 export declare const DEFAULT_SOCKET_PATH: string;
 export declare const REQUEST_TIMEOUT_MS = 5000;
-export declare const RECONNECT_DELAY_MS = 3000;
 export declare const INITIAL_RECONNECT_DELAY_MS = 1000;
 export declare const MAX_RECONNECT_DELAY_MS = 30000;
 export declare const HEARTBEAT_INTERVAL_MS = 5000;
 export declare const HEARTBEAT_METADATA_PROVIDER_TIMEOUT_MS = 2500;
-/** Compute reconnect delay with exponential backoff and jitter. */
+/** Compute reconnect delay with exponential backoff and jitter (±25%). */
 export declare function computeReconnectDelay(attempt: number, random?: number): number;
+/**
+ * A single-use, broker-issued wake fence presented by a runtime that the broker
+ * cold-launched to revive a hibernated identity. Consumed on the first
+ * successful register and never replayed on reconnect.
+ */
+interface WakeFence {
+    wakeLeaseId: string;
+    fenceToken: number;
+    runtimeGeneration: number;
+    reservationNonce: string;
+}
 export interface AgentBroadcastResult {
     channel: string;
     messageIds: number[];
@@ -59,11 +69,18 @@ export interface BrokerClientAuthOptions {
     meshSecret?: string;
     meshSecretPath?: string;
 }
+export interface BrokerClientTimingOptions {
+    /** @internal Allows tests to exercise reconnect behavior without waiting for production backoff. */
+    reconnectDelayMs?: (attempt: number) => number;
+}
+export type BrokerClientOptions = BrokerConnectOpts & BrokerClientAuthOptions & BrokerClientTimingOptions;
 export declare class BrokerClient {
     private readonly connectOpts;
     private readonly meshSecret;
     private readonly meshSecretPath;
+    private readonly reconnectDelayMs;
     private socket;
+    private connectingSocket;
     private connected;
     private shuttingDown;
     private reconnectTimer;
@@ -79,14 +96,14 @@ export declare class BrokerClient {
     private nextId;
     private readonly pending;
     private buffer;
-    constructor(opts?: string | (BrokerConnectOpts & BrokerClientAuthOptions));
+    constructor(opts?: string | BrokerClientOptions);
     connect(): Promise<void>;
     disconnect(): void;
     disconnectGracefully(): Promise<void>;
     isConnected(): boolean;
     private resolveMeshSecret;
     private authenticateIfNeeded;
-    register(name: string, emoji: string, metadata?: Record<string, unknown>, stableId?: string): Promise<{
+    register(name: string, emoji: string, metadata?: Record<string, unknown>, stableId?: string, wakeFence?: WakeFence): Promise<{
         agentId: string;
         name: string;
         emoji: string;

package/dist/broker/client.js

@@ -1,4 +1,5 @@
 import * as net from "node:net";
+import { computeBackoffDelay, withTimeout } from "@pinet/transport-core/async";
 import { readMeshSecret } from "./auth.js";
 import { DEFAULT_SOCKET_PATH as PINET_DEFAULT_SOCKET_PATH } from "./paths.js";
 import { assertLoopbackTcpHost } from "./raw-tcp-loopback.js";
@@ -6,31 +7,17 @@ import { RPC_AGENT_NAME_CONFLICT, RPC_METHOD_NOT_FOUND } from "./types.js";
 // ─── Constants (exported for testing) ────────────────────
 export const DEFAULT_SOCKET_PATH = PINET_DEFAULT_SOCKET_PATH;
 export const REQUEST_TIMEOUT_MS = 5000;
-export const RECONNECT_DELAY_MS = 3000;
 export const INITIAL_RECONNECT_DELAY_MS = 1000;
 export const MAX_RECONNECT_DELAY_MS = 30000;
 export const HEARTBEAT_INTERVAL_MS = 5000;
 export const HEARTBEAT_METADATA_PROVIDER_TIMEOUT_MS = 2500;
-function withTimeout(promise, timeoutMs) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
-        timer.unref?.();
-        promise.then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        }, (error) => {
-            clearTimeout(timer);
-            reject(error instanceof Error ? error : new Error(String(error)));
-        });
-    });
-}
-/** Compute reconnect delay with exponential backoff and jitter. */
+/** Compute reconnect delay with exponential backoff and jitter (±25%). */
 export function computeReconnectDelay(attempt, random = Math.random()) {
-    const baseDelay = INITIAL_RECONNECT_DELAY_MS * Math.pow(2, attempt);
-    const capped = Math.min(baseDelay, MAX_RECONNECT_DELAY_MS);
-    // Add jitter: ±25%
-    const jitter = capped * (0.75 + random * 0.5);
-    return Math.round(jitter);
+    return computeBackoffDelay(attempt, {
+        initialMs: INITIAL_RECONNECT_DELAY_MS,
+        maxMs: MAX_RECONNECT_DELAY_MS,
+        random,
+    });
 }
 function createRpcRequestError(method, error) {
     const err = new Error(error.message);
@@ -78,7 +65,9 @@ export class BrokerClient {
     connectOpts;
     meshSecret;
     meshSecretPath;
+    reconnectDelayMs;
     socket = null;
+    connectingSocket = null;
     connected = false;
     shuttingDown = false;
     reconnectTimer = null;
@@ -95,6 +84,10 @@ export class BrokerClient {
     pending = new Map();
     buffer = "";
     constructor(opts) {
+        this.reconnectDelayMs =
+            typeof opts === "object" && opts !== null
+                ? (opts.reconnectDelayMs ?? computeReconnectDelay)
+                : computeReconnectDelay;
         if (opts === undefined) {
             this.connectOpts = { path: DEFAULT_SOCKET_PATH };
             this.meshSecret = null;
@@ -139,7 +132,10 @@ export class BrokerClient {
         }
         this.stopHeartbeat();
         this.rejectAllPending(new Error("Client disconnected"));
+        const connectingSocket = this.connectingSocket;
+        this.connectingSocket = null;
         try {
+            connectingSocket?.destroy();
             this.socket?.destroy();
         }
         catch {
@@ -198,13 +194,14 @@ export class BrokerClient {
         }
     }
     // ─── Registration ────────────────────────────────────
-    async register(name, emoji, metadata, stableId) {
+    async register(name, emoji, metadata, stableId, wakeFence) {
         this.registrationSnapshot = {
             name,
             emoji,
             ...(metadata ? { metadata } : {}),
             ...(stableId ? { stableId } : {}),
             ...(name.trim().length === 0 ? { brokerAssignedIdentity: true } : {}),
+            ...(wakeFence ? { wakeFence } : {}),
         };
         return this.performRegister(this.registrationSnapshot);
     }
@@ -368,7 +365,12 @@ export class BrokerClient {
     }
     async searchAgentSessions(options = {}) {
         try {
-            return (await this.request("agent.sessions.search", options));
+            const sessions = (await this.request("agent.sessions.search", options));
+            return sessions.map((session) => ({
+                ...session,
+                runtimeKind: session.runtimeKind ?? (session.tmuxSession ? "tmux" : null),
+                runtimeLocator: session.runtimeLocator ?? (session.runtimeKind === "herdr" ? null : session.tmuxSession),
+            }));
         }
         catch (err) {
             if (isRpcMethodNotFoundError(err, "agent.sessions.search")) {
@@ -480,7 +482,7 @@ export class BrokerClient {
     scheduleReconnect() {
         if (this.shuttingDown || this.reconnectTimer)
             return;
-        const delay = computeReconnectDelay(this.reconnectAttempt);
+        const delay = this.reconnectDelayMs(this.reconnectAttempt);
         this.reconnectAttempt++;
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
@@ -491,7 +493,27 @@ export class BrokerClient {
     connectSocket() {
         return new Promise((resolve, reject) => {
             const sock = net.createConnection(this.connectOpts);
+            this.connectingSocket = sock;
+            let settled = false;
+            const rejectConnect = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (this.connectingSocket === sock) {
+                    this.connectingSocket = null;
+                }
+                reject(error);
+            };
             sock.on("connect", () => {
+                if (this.shuttingDown) {
+                    rejectConnect(new Error("Client disconnected while connecting"));
+                    sock.destroy();
+                    return;
+                }
+                settled = true;
+                if (this.connectingSocket === sock) {
+                    this.connectingSocket = null;
+                }
                 this.socket = sock;
                 this.connected = true;
                 this.buffer = "";
@@ -501,6 +523,12 @@ export class BrokerClient {
                 this.onData(chunk.toString("utf-8"));
             });
             sock.on("close", () => {
+                if (this.connectingSocket === sock) {
+                    this.connectingSocket = null;
+                }
+                if (!settled) {
+                    rejectConnect(new Error("Socket closed before connection completed"));
+                }
                 const wasConnected = this.connected;
                 this.connected = false;
                 this.socket = null;
@@ -512,8 +540,8 @@ export class BrokerClient {
                 }
             });
             sock.on("error", (err) => {
-                if (!this.connected) {
-                    reject(err);
+                if (!settled) {
+                    rejectConnect(err);
                 }
                 // If already connected, the close event handles cleanup
             });
@@ -526,14 +554,26 @@ export class BrokerClient {
             pid: process.pid,
             ...(snapshot.metadata ? { metadata: snapshot.metadata } : {}),
             ...(snapshot.stableId ? { stableId: snapshot.stableId } : {}),
+            ...(snapshot.wakeFence
+                ? {
+                    wakeLeaseId: snapshot.wakeFence.wakeLeaseId,
+                    fenceToken: snapshot.wakeFence.fenceToken,
+                    runtimeGeneration: snapshot.wakeFence.runtimeGeneration,
+                    reservationNonce: snapshot.wakeFence.reservationNonce,
+                }
+                : {}),
         }));
+        // Retain a reconnect snapshot but drop the single-use wake fence so a
+        // reconnect never replays a consumed generation reservation.
         this.registrationSnapshot = snapshot.brokerAssignedIdentity
             ? {
                 ...snapshot,
+                wakeFence: undefined,
                 ...(result.metadata ? { metadata: result.metadata } : {}),
             }
             : {
                 ...snapshot,
+                wakeFence: undefined,
                 name: result.name,
                 emoji: result.emoji,
                 ...(result.metadata ? { metadata: result.metadata } : {}),

package/dist/broker/hibernation-activation-authority.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Capture the activation authority from the process-launch environment ONCE and
+ * freeze it for the process lifetime. Idempotent: the first call wins, and any
+ * later environment or settings mutation cannot change the frozen value. Returns
+ * the frozen authority. Call this explicitly at broker start so the freeze point
+ * is deterministic; reads via {@link hibernationActivationAuthorized} also
+ * freeze lazily on first use.
+ *
+ * Accepts `1`, `true`, `yes`, or `on` (case-insensitive, trimmed) as authorized;
+ * everything else — including unset/empty — is unauthorized (the production
+ * default, a strict no-op).
+ */
+export declare function freezeHibernationActivationAuthority(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The frozen live-runtime activation authority. Lazily freezes on first read
+ * from the process-launch environment when {@link freezeHibernationActivationAuthority}
+ * has not run yet, so the gate is always a process-lifetime constant. Config
+ * reloads and settings edits can never flip it.
+ */
+export declare function hibernationActivationAuthorized(): boolean;
+/** Test-only: clear the frozen value so a test can re-capture a chosen env. */
+export declare function __resetHibernationActivationAuthorityForTest(): void;

package/dist/broker/hibernation-activation-authority.js

@@ -0,0 +1,51 @@
+// Durable, non-reloadable hibernation runtime-activation authority.
+//
+// The Phase B live process/tmux adapters must be activated ONLY by a durable
+// authority captured at broker start and FROZEN for the entire process
+// lifetime. This deliberately does NOT read agent-editable `SlackBridgeSettings`
+// (which pi re-reads on config reload): there must be NO settings, reload, or
+// other in-process path that can elevate a running broker into live-runtime
+// activation. The single source of truth is an external, process-launch
+// environment variable, captured exactly once.
+//
+// Security rationale: an attacker (or a well-meaning agent) who can edit the
+// broker's settings file or trigger a settings reload must never be able to turn
+// on the live runtime. Requiring an external launch-environment variable moves
+// the activation decision to whoever started the broker process and freezes it
+// for the lifetime of that process.
+/** External process-launch env var that authorizes live-runtime activation. */
+const ACTIVATION_ENV_VAR = "PINET_HIBERNATION_RUNTIME_ACTIVATION";
+/** Captured once at broker start; never re-read afterwards. */
+let frozen;
+/**
+ * Capture the activation authority from the process-launch environment ONCE and
+ * freeze it for the process lifetime. Idempotent: the first call wins, and any
+ * later environment or settings mutation cannot change the frozen value. Returns
+ * the frozen authority. Call this explicitly at broker start so the freeze point
+ * is deterministic; reads via {@link hibernationActivationAuthorized} also
+ * freeze lazily on first use.
+ *
+ * Accepts `1`, `true`, `yes`, or `on` (case-insensitive, trimmed) as authorized;
+ * everything else — including unset/empty — is unauthorized (the production
+ * default, a strict no-op).
+ */
+export function freezeHibernationActivationAuthority(env = process.env) {
+    if (frozen === undefined) {
+        const raw = env[ACTIVATION_ENV_VAR]?.trim().toLowerCase();
+        frozen = raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+    }
+    return frozen;
+}
+/**
+ * The frozen live-runtime activation authority. Lazily freezes on first read
+ * from the process-launch environment when {@link freezeHibernationActivationAuthority}
+ * has not run yet, so the gate is always a process-lifetime constant. Config
+ * reloads and settings edits can never flip it.
+ */
+export function hibernationActivationAuthorized() {
+    return freezeHibernationActivationAuthority();
+}
+/** Test-only: clear the frozen value so a test can re-capture a chosen env. */
+export function __resetHibernationActivationAuthorityForTest() {
+    frozen = undefined;
+}

package/dist/broker/hibernation-activation.d.ts

@@ -0,0 +1,75 @@
+import { HibernationOrchestrator, type HibernationOrchestratorConfig, type RuntimeLaunchContext, type StrandedWakeRecovery } from "@pinet/broker-core";
+import type { AgentRuntimeSpec } from "@pinet/broker-core/types";
+import type { BrokerDB } from "./schema.js";
+import { resolveVcsIdentity } from "./hibernation-runtime-adapters.js";
+import { type SpawnAuthoredRuntimeFacts } from "./hibernation-runtime-helpers.js";
+/** Optional command runner override (git remote resolution); defaults to real `execFile`. */
+type VcsRunner = Parameters<typeof resolveVcsIdentity>[1];
+/**
+ * The DEFAULT-OFF live-runtime gate. Live process/tmux composition happens ONLY
+ * when the durable, process-lifetime activation authority — captured at broker
+ * start from the external launch environment, never agent-editable settings — is
+ * set. Config reloads and settings edits can NEVER flip it, so the production
+ * default (authority unset) keeps the broker on the `activation_pending` stub
+ * with zero live-runtime side effects. Operational permission (enabled / mode /
+ * repo allowlist) is a SEPARATE settings policy enforced by the command layer;
+ * this gate only decides whether the real machinery is wired in at all.
+ */
+export declare function hibernationRuntimeActive(): boolean;
+export interface HibernationRuntimeDeps {
+    db: BrokerDB;
+    /** Broker owner id recorded as `brokerOwnerId`/`brokerInstanceId` on managed rows. */
+    brokerInstanceId: string;
+    /** slack-bridge extension entry a woken runtime loads (`pi -e <path>`). */
+    extensionEntryPath: string;
+    /** Base PINET_* env re-establishing the mesh connection for a woken worker. */
+    baseLaunchEnv: Record<string, string>;
+    /** Broker env var NAMES (never values) re-exported into a woken runtime when present. */
+    inheritedEnvKeys: string[];
+    config?: Partial<HibernationOrchestratorConfig>;
+    /**
+     * Confirm the woken runtime registered and its reserved generation was accepted.
+     * PRODUCTION leaves this undefined: the orchestrator's default polls the broker
+     * DB until the socket server's fenced-registration handler accepts the woken
+     * worker's generation. Injectable so an isolated E2E can key acceptance off the
+     * REAL respawned process coming back alive instead of a live socket handshake.
+     */
+    awaitRuntimeRegistration?: (ctx: RuntimeLaunchContext) => Promise<boolean>;
+}
+/**
+ * Seam 1 — compose the real orchestrator-backed executor.
+ *
+ * The process and tmux controllers are constructed INDEPENDENTLY: the immutable
+ * launch generation rides inside the attempt handle `respawnRuntime` returns, so
+ * attempt-scoped stop/liveness bind to the exact launched process with no shared
+ * registry. The returned {@link HibernationOrchestrator} structurally satisfies
+ * `HibernateCommandExecutor & WakeCommandExecutor`, so it drops directly into the
+ * command executor slot in place of the `activation_pending` stub — but only the
+ * caller's {@link hibernationRuntimeActive} gate decides when to use it.
+ */
+export declare function createHibernationOrchestrator(deps: HibernationRuntimeDeps): HibernationOrchestrator;
+/** Broker-authored spawn facts minus the VCS identity (derived here from the git remote). */
+type SpawnRuntimeSpecFactsWithoutVcs<T extends SpawnAuthoredRuntimeFacts> = T extends SpawnAuthoredRuntimeFacts ? Omit<T, "vcsIdentity"> : never;
+export type SpawnRuntimeSpecFacts = SpawnRuntimeSpecFactsWithoutVcs<SpawnAuthoredRuntimeFacts>;
+/**
+ * Seam 2 — persist a durable, broker-authored runtime spec at worker spawn.
+ *
+ * The canonical `owner/repo` VCS identity (the ONLY value the repo allowlist
+ * authorizes against) is resolved HERE from the runtime's actual git `origin`
+ * remote — never from filesystem directory names. Fails closed: an unresolvable
+ * remote records `vcsIdentity: null` (the fail-closed gate then refuses), and a
+ * spec that could not be safely hibernated/woken (missing session/tmux/repo
+ * locators) is never written. Returns the persisted spec, or null when the facts
+ * do not compose a durable spec.
+ */
+export declare function persistSpawnedRuntimeSpec(db: BrokerDB, facts: SpawnRuntimeSpecFacts, runner?: VcsRunner): Promise<AgentRuntimeSpec | null>;
+/**
+ * Seam 3 — reconcile crash-stranded wake state at broker startup.
+ *
+ * Must run BEFORE the broker socket accepts new registrations so a stranded
+ * `waking`/`dispatching` row is completed, quarantined, or requeued deterministically
+ * rather than racing an incoming (possibly duplicate) wake registration. This is a
+ * synchronous DB reconciliation; it launches nothing.
+ */
+export declare function recoverStrandedWakesBeforeRegistrations(orchestrator: HibernationOrchestrator): StrandedWakeRecovery[];
+export {};