@pinet/slack-bridge 0.2.4 → 0.2.7

package/dist/pinet-commands.d.ts

@@ -3,6 +3,7 @@ import { type FollowerRuntimeDiagnostic, type SlackBridgeSettings } from "./help
 import { type LoggedActivityLogEntry } from "./activity-log.js";
 import { type SlackScopeDiagnostics } from "./slack-scope-diagnostics.js";
 import type { SlackBridgeRuntimeMode } from "./runtime-mode.js";
+import type { BrokerLockInspection, BrokerSocketProbeResult, ReplaceBrokerOwnerResult } from "./broker/index.js";
 import type { RalphSnoozeStatus } from "./ralph-loop.js";
 import type { SubtreeBrokerStatus, SubtreeSpawnInput, SubtreeSpawnResult } from "./subtree-broker-runtime.js";
 export interface PinetCommandsDeps {
@@ -45,7 +46,9 @@ export interface PinetCommandsDeps {
     lastBrokerControlPlaneHomeTabRefreshAt: () => string | null;
     lastBrokerControlPlaneHomeTabError: () => string | null;
     subtreeBrokerStatus: () => SubtreeBrokerStatus;
+    inspectGlobalBroker: () => Promise<GlobalBrokerInspection>;
     getPinetRegistrationBlockReason: () => string;
+    replaceGlobalBroker: (ctx: ExtensionContext) => Promise<ReplaceBrokerOwnerResult>;
     connectAsBroker: (ctx: ExtensionContext) => Promise<void>;
     connectAsFollower: (ctx: ExtensionContext) => Promise<void>;
     reloadPinetRuntime: (ctx: ExtensionContext) => Promise<void>;
@@ -65,7 +68,7 @@ export interface PinetCommandsDeps {
         queuedInboxCount: number;
         drainedQueuedInbox: boolean;
     }>;
-    applyLocalAgentIdentity: (name: string, emoji: string, personality: string | null) => void;
+    applyLocalAgentIdentity: (name: string, emoji: string, personality: string | null) => Promise<void>;
     setExtStatus: (ctx: ExtensionContext, state: "ok" | "reconnecting" | "error" | "off") => void;
     setExtCtx: (ctx: ExtensionContext) => void;
 }
@@ -73,3 +76,13 @@ export type PinetCommandAction = "start" | "follow" | "unfollow" | "reload" | "e
 export declare function formatPinetCommandHelp(): string;
 export declare function runPinetCommandAction(deps: PinetCommandsDeps, action: PinetCommandAction, args: string, ctx: ExtensionContext, usageCommand?: string): Promise<void>;
 export declare function registerPinetCommands(pi: ExtensionAPI, deps: PinetCommandsDeps): void;
+export interface GlobalBrokerInspection {
+    lock: BrokerLockInspection;
+    probe: BrokerSocketProbeResult | null;
+}
+/**
+ * Machine-wide broker state line for `/pinet status`, so a disconnected
+ * session — precisely the one that needs recovery — can see who holds the
+ * broker lock and whether that broker is healthy (issue #951).
+ */
+export declare function formatGlobalBrokerReport(report: GlobalBrokerInspection): string;

package/dist/pinet-commands.js

@@ -4,7 +4,11 @@ import { formatRecentActivityLogEntries } from "./activity-log.js";
 import { formatRuntimeGuardrailsPosture } from "./guardrails.js";
 import { formatSlackScopeDiagnosticsStatus, } from "./slack-scope-diagnostics.js";
 const PINET_PRIMARY_COMMANDS = [
-    { action: "start", args: "", description: "Start as the mesh broker" },
+    {
+        action: "start",
+        args: "[replace]",
+        description: "Start as the mesh broker (replace: take over a stale/stranded broker)",
+    },
     { action: "follow", args: "", description: "Connect as a follower worker" },
     { action: "unfollow", args: "", description: "Disconnect from the broker" },
     { action: "reload", args: "<agent>", description: "Ask another agent to reload" },
@@ -23,7 +27,7 @@ const PINET_SECONDARY_COMMANDS = [
     { action: "rename", args: "[name]", description: "Rename this Pinet agent" },
 ];
 // ─── Registration ────────────────────────────────────────
-function abortCurrentTurnBeforeBrokerReload(ctx) {
+function abortCurrentTurnBeforeRuntimeReload(ctx) {
     if (ctx.isIdle?.() ?? true) {
         return;
     }
@@ -106,7 +110,7 @@ function normalizePinetCommandAction(rawAction) {
 export async function runPinetCommandAction(deps, action, args, ctx, usageCommand = `/pinet ${action}`) {
     switch (action) {
         case "start":
-            await runPinetStart(deps, ctx);
+            await runPinetStart(deps, args, ctx);
             return;
         case "follow":
             await runPinetFollow(deps, ctx);
@@ -124,14 +128,23 @@ export async function runPinetCommandAction(deps, action, args, ctx, usageComman
             await runPinetFree(deps, ctx);
             return;
         case "status":
-            runPinetStatus(deps, ctx);
+            await runPinetStatus(deps, ctx);
             return;
         case "logs":
             runPinetLogs(deps, ctx);
             return;
-        case "rename":
-            runPinetRename(deps, args, ctx);
+        case "rename": {
+            const newName = args.trim();
+            if (newName) {
+                await deps.applyLocalAgentIdentity(newName, deps.agentEmoji(), deps.agentPersonality());
+            }
+            else {
+                const identity = generateAgentName(undefined, deps.runtimeMode() === "broker" ? "broker" : "worker");
+                await deps.applyLocalAgentIdentity(identity.name, identity.emoji, deps.agentPersonality());
+            }
+            ctx.ui.notify(`${deps.agentEmoji()} Agent renamed to: ${deps.agentName()}`, "info");
             return;
+        }
         case "snooze":
             runPinetSnooze(deps, args, ctx);
             return;
@@ -158,15 +171,21 @@ export function registerPinetCommands(pi, deps) {
         },
     });
 }
-async function runPinetStart(deps, ctx) {
+async function runPinetStart(deps, args, ctx) {
     if (deps.pinetRegistrationBlocked()) {
         ctx.ui.notify(deps.getPinetRegistrationBlockReason(), "warning");
         return;
     }
     deps.setExtCtx(ctx);
+    const trimmedArgs = args.trim().toLowerCase();
+    const wantReplace = ["replace", "--replace", "takeover"].includes(trimmedArgs);
+    if (trimmedArgs && !wantReplace) {
+        ctx.ui.notify(`Unknown /pinet start option: ${args.trim()}\nUsage: /pinet start [replace]`, "warning");
+        return;
+    }
     if (deps.runtimeMode() === "broker") {
         try {
-            abortCurrentTurnBeforeBrokerReload(ctx);
+            abortCurrentTurnBeforeRuntimeReload(ctx);
             ctx.ui.notify("Pinet broker already running — reloading current runtime", "info");
             await deps.reloadPinetRuntime(ctx);
         }
@@ -176,6 +195,26 @@ async function runPinetStart(deps, ctx) {
         }
         return;
     }
+    if (wantReplace) {
+        let replaceResult;
+        try {
+            replaceResult = await deps.replaceGlobalBroker(ctx);
+        }
+        catch (err) {
+            ctx.ui.notify(`Pinet broker replace failed: ${errorMsg(err)}`, "error");
+            deps.setExtStatus(ctx, "error");
+            return;
+        }
+        const stepsText = replaceResult.steps.length
+            ? `\n${replaceResult.steps.map((step) => `• ${step}`).join("\n")}`
+            : "";
+        if (replaceResult.outcome === "failed" || replaceResult.outcome === "owner-changed") {
+            ctx.ui.notify(`Pinet broker replace ${replaceResult.outcome === "failed" ? "failed" : "aborted"}: ${replaceResult.error ?? "unknown error"}${stepsText}`, "error");
+            deps.setExtStatus(ctx, "error");
+            return;
+        }
+        ctx.ui.notify(`Pinet broker replace: ${replaceResult.outcome}.${stepsText}`, "info");
+    }
     try {
         await deps.connectAsBroker(ctx);
     }
@@ -189,13 +228,20 @@ async function runPinetFollow(deps, ctx) {
         ctx.ui.notify(deps.getPinetRegistrationBlockReason(), "warning");
         return;
     }
-    if (deps.runtimeMode() === "follower") {
+    if (deps.runtimeMode() === "follower" && deps.runtimeConnected()) {
         ctx.ui.notify("Pinet already running (follower)", "info");
         return;
     }
     deps.setExtCtx(ctx);
     try {
-        await deps.connectAsFollower(ctx);
+        if (deps.runtimeMode() === "follower") {
+            abortCurrentTurnBeforeRuntimeReload(ctx);
+            ctx.ui.notify("Pinet follower disconnected — reconnecting...", "info");
+            await deps.reloadPinetRuntime(ctx);
+        }
+        else {
+            await deps.connectAsFollower(ctx);
+        }
         ctx.ui.notify(`${deps.agentEmoji()} ${deps.agentName()} — following broker`, "info");
     }
     catch (err) {
@@ -475,8 +521,43 @@ async function runPinetSubtree(deps, args, ctx) {
         ctx.ui.notify(`Subtree broker start failed: ${errorMsg(err)}`, "error");
     }
 }
-function runPinetStatus(deps, ctx) {
+/**
+ * Machine-wide broker state line for `/pinet status`, so a disconnected
+ * session — precisely the one that needs recovery — can see who holds the
+ * broker lock and whether that broker is healthy (issue #951).
+ */
+export function formatGlobalBrokerReport(report) {
+    const { lock, probe } = report;
+    switch (lock.state) {
+        case "none":
+            return "Global broker: none running on this machine (lock free). Use /pinet start.";
+        case "unreadable":
+            return "Global broker: unreadable lock file — /pinet start will reclaim it.";
+        case "stale-dead":
+            return `Global broker: stale lock from dead pid ${lock.owner.pid} — /pinet start will reclaim it.`;
+        case "stale-pid-reused":
+            return `Global broker: lock pid ${lock.owner.pid} was reused by an unrelated process — /pinet start will reclaim it.`;
+        case "alive": {
+            const since = lock.owner.createdAt ? ` since ${lock.owner.createdAt}` : "";
+            if (probe === "healthy") {
+                return `Global broker: active (pid ${lock.owner.pid}${since}). Use /pinet follow to join it, or /pinet start replace to take it over.`;
+            }
+            const socketState = probe === "unreachable" ? "unreachable" : "unresponsive";
+            return `Global broker: pid ${lock.owner.pid} holds the lock${since} but the broker socket is ${socketState} — likely stranded. Use /pinet start replace to recover.`;
+        }
+    }
+}
+async function runPinetStatus(deps, ctx) {
     const mode = deps.runtimeMode();
+    let globalBrokerInfo = [];
+    if (mode === "off" || mode === "single") {
+        try {
+            globalBrokerInfo = [formatGlobalBrokerReport(await deps.inspectGlobalBroker())];
+        }
+        catch (err) {
+            globalBrokerInfo = [`Global broker: inspection failed (${errorMsg(err)})`];
+        }
+    }
     const ownedCount = [...deps.threads().values()].filter((t) => agentOwnsThread(t.owner, deps.agentName(), deps.agentAliases(), deps.agentOwnerToken())).length;
     const users = deps.allowedUsers();
     const s = deps.settings();
@@ -541,6 +622,7 @@ function runPinetStatus(deps, ctx) {
         ...ralphSnoozeInfo,
         ...brokerHomeTabInfo,
         ...subtreeBrokerInfo,
+        ...globalBrokerInfo,
     ].join("\n"), "info");
 }
 function runPinetLogs(deps, ctx) {
@@ -551,17 +633,6 @@ function runPinetLogs(deps, ctx) {
         formatRecentActivityLogEntries(deps.recentActivityLogEntries(10)),
     ].join("\n\n"), s.logChannel ? "info" : "warning");
 }
-function runPinetRename(deps, args, ctx) {
-    const newName = args.trim();
-    if (!newName) {
-        const fresh = generateAgentName(undefined, deps.runtimeMode() === "broker" ? "broker" : "worker");
-        deps.applyLocalAgentIdentity(fresh.name, fresh.emoji, deps.agentPersonality());
-    }
-    else {
-        deps.applyLocalAgentIdentity(newName, deps.agentEmoji(), deps.agentPersonality());
-    }
-    ctx.ui.notify(`${deps.agentEmoji()} Agent renamed to: ${deps.agentName()}`, "info");
-}
 function errorMsg(err) {
     return err instanceof Error ? err.message : String(err);
 }

package/dist/pinet-mesh-ops.d.ts

@@ -1,6 +1,8 @@
 import { type AgentMessageStorage } from "./broker/agent-messaging.js";
 import type { AgentInfo, AgentSessionSearchInfo, AgentSessionSearchOptions, AgentSessionSummary, TaskAssignmentInfo, TaskAssignmentKind } from "./broker/types.js";
 import type { ActivityLogEntry } from "./activity-log.js";
+export type PinetMeshOpsAgentMetadata = Record<string, unknown>;
+export type PinetMeshOpsMessageMetadata = Record<string, unknown>;
 export interface PinetMeshOpsAgentRecord {
     emoji: string;
     name: string;
@@ -9,7 +11,7 @@ export interface PinetMeshOpsAgentRecord {
     stableId?: string | null;
     session?: AgentSessionSummary | null;
     status: "working" | "idle";
-    metadata: Record<string, unknown> | null;
+    metadata: PinetMeshOpsAgentMetadata | null;
     lastHeartbeat: string;
     lastSeen?: string;
     disconnectedAt?: string | null;
@@ -59,7 +61,7 @@ export interface PinetMeshOpsFollowerAgentRecord extends Omit<PinetMeshOpsAgentR
     status?: PinetMeshOpsAgentRecord["status"] | null;
 }
 export interface PinetMeshOpsFollowerClientPort {
-    sendAgentMessage: (target: string, body: string, metadata?: Record<string, unknown>) => Promise<number>;
+    sendAgentMessage: (target: string, body: string, metadata?: PinetMeshOpsMessageMetadata) => Promise<number>;
     scheduleWakeup: (fireAt: string, message: string) => Promise<{
         id: number;
         fireAt: string;
@@ -74,7 +76,7 @@ export interface PinetMeshOpsDeps {
     getActiveBrokerSelfId: () => string | null;
     getAgentName: () => string;
     getFollowerClient: () => PinetMeshOpsFollowerClientPort | null;
-    sendSubtreeAgentMessage?: (target: string, body: string, metadata?: Record<string, unknown>) => Promise<{
+    sendSubtreeAgentMessage?: (target: string, body: string, metadata?: PinetMeshOpsMessageMetadata) => Promise<{
         messageId: number;
         target: string;
         threadId: string;
@@ -83,7 +85,7 @@ export interface PinetMeshOpsDeps {
     logActivity: (entry: ActivityLogEntry) => void;
 }
 export interface PinetMeshOps {
-    sendPinetAgentMessage: (target: string, body: string, metadata?: Record<string, unknown>) => Promise<{
+    sendPinetAgentMessage: (target: string, body: string, metadata?: PinetMeshOpsMessageMetadata) => Promise<{
         messageId: number;
         target: string;
         transferredThreadId?: string;

package/dist/pinet-mesh-ops.js

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { normalizeOutgoingPinetControlMessage } from "./helpers.js";
+import { normalizeOutgoingPinetControlMessage, normalizeOutgoingPinetSteeringMessage, } from "./helpers.js";
 import { dispatchBroadcastAgentMessage, dispatchDirectAgentMessage, isBroadcastChannelTarget, } from "./broker/agent-messaging.js";
 import { summarizePinetStableId } from "./pinet-session-formatting.js";
 import { extractTaskAssignmentsFromMessage } from "./task-assignments.js";
@@ -13,6 +13,13 @@ function prepareOutgoingPinetAgentMessage(body, metadata) {
             metadata: control.metadata,
         };
     }
+    const steering = normalizeOutgoingPinetSteeringMessage(body, metadata);
+    if (steering) {
+        return {
+            body: steering.body,
+            metadata: steering.metadata,
+        };
+    }
     return { body, metadata };
 }
 function getThreadOwnershipTransferMetadata(metadata) {

package/dist/pinet-runtime-composition.d.ts

@@ -19,9 +19,10 @@ export interface ConnectPinetRuntimeAdaptersOptions {
     broker: Pick<Broker, "addAdapter">;
     bindings: PinetRuntimeAdapterBinding[];
     onInbound: (message: InboundMessage) => void;
+    signal?: AbortSignal;
 }
 export interface ConnectPinetRuntimeAdaptersResult {
     botUserId: string | null;
 }
 export declare function buildPinetRuntimeAdapterBindings(factories: readonly PinetRuntimeAdapterFactory[], context: PinetRuntimeAdapterFactoryContext): Promise<PinetRuntimeAdapterBinding[]>;
-export declare function connectPinetRuntimeAdapters({ broker, bindings, onInbound, }: ConnectPinetRuntimeAdaptersOptions): Promise<ConnectPinetRuntimeAdaptersResult>;
+export declare function connectPinetRuntimeAdapters({ broker, bindings, onInbound, signal, }: ConnectPinetRuntimeAdaptersOptions): Promise<ConnectPinetRuntimeAdaptersResult>;

package/dist/pinet-runtime-composition.js

@@ -8,13 +8,24 @@ export async function buildPinetRuntimeAdapterBindings(factories, context) {
     }
     return bindings;
 }
-export async function connectPinetRuntimeAdapters({ broker, bindings, onInbound, }) {
+export async function connectPinetRuntimeAdapters({ broker, bindings, onInbound, signal, }) {
     let botUserId = null;
     for (const binding of bindings) {
+        signal?.throwIfAborted();
         binding.adapter.onInbound(onInbound);
         broker.addAdapter(binding.adapter);
-        await binding.adapter.connect();
-        botUserId ??= binding.getBotUserId?.() ?? null;
+        const abortConnect = () => {
+            void binding.adapter.disconnect().catch(() => undefined);
+        };
+        signal?.addEventListener("abort", abortConnect, { once: true });
+        try {
+            await binding.adapter.connect();
+            signal?.throwIfAborted();
+            botUserId ??= binding.getBotUserId?.() ?? null;
+        }
+        finally {
+            signal?.removeEventListener("abort", abortConnect);
+        }
     }
     return { botUserId };
 }

package/dist/pinet-session-formatting.d.ts

@@ -5,9 +5,33 @@ export interface ParsedPinetStableId {
     locator: string;
     hasPath: boolean;
 }
+export type PinetSessionFullDetails = AgentSessionSearchInfo & {
+    session: AgentSessionSummary | null;
+    jsonlPath?: string;
+};
+export interface PinetSessionCompactDetails {
+    agentId: string;
+    agentName: string;
+    emoji: string;
+    pid: number;
+    status: AgentSessionSearchInfo["status"];
+    health: "disconnected" | "live";
+    session: string | null;
+    sessionKind: AgentSessionKind | null;
+    host: string | null;
+    repo: string | null;
+    branch: string | null;
+    runtimeKind: AgentSessionSearchInfo["runtimeKind"];
+    runtimeLocator: string | null;
+    tmuxSession: string | null;
+    lastSeen: string;
+    disconnectedAt: string | null;
+    relatedThreadIds: string[];
+    matchedBy: string[];
+}
 export declare function parsePinetStableId(stableId: string | null | undefined): ParsedPinetStableId | null;
 export declare function summarizePinetStableId(stableId: string | null | undefined): AgentSessionSummary | null;
 export declare function getPinetSessionPath(stableId: string | null | undefined): string | null;
 export declare function getPinetSessionFilename(stableId: string | null | undefined): string | null;
-export declare function buildPinetSessionFullDetails(session: AgentSessionSearchInfo): Record<string, unknown>;
-export declare function buildPinetSessionCompactDetails(session: AgentSessionSearchInfo): Record<string, unknown>;
+export declare function buildPinetSessionFullDetails(session: AgentSessionSearchInfo): PinetSessionFullDetails;
+export declare function buildPinetSessionCompactDetails(session: AgentSessionSearchInfo): PinetSessionCompactDetails;

package/dist/pinet-session-formatting.js

@@ -71,6 +71,8 @@ export function buildPinetSessionCompactDetails(session) {
         host: summary?.host ?? null,
         repo: session.repo,
         branch: session.branch,
+        runtimeKind: session.runtimeKind,
+        runtimeLocator: session.runtimeLocator,
         tmuxSession: session.tmuxSession,
         lastSeen: session.lastSeen,
         disconnectedAt: session.disconnectedAt,

package/dist/pinet-tools.d.ts

@@ -1,6 +1,8 @@
 import { type PinetReadOptions, type PinetReadResult } from "@pinet/pinet-core/pinet-read-formatting";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type AgentLifecycleStatus, type HibernationCommandResult } from "@pinet/broker-core";
 import type { RalphSnoozeStatus } from "./ralph-loop.js";
+import { type SubtreeSpawnLaunchHandle } from "./subtree-broker-runtime.js";
 import type { AgentSessionSearchInfo, AgentSessionSearchOptions, AgentSessionSummary, PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput } from "./broker/types.js";
 export interface PinetToolsAgentRecord {
     emoji: string;
@@ -29,10 +31,12 @@ export interface PinetSubtreeSpawnInput {
     repo: string;
     role?: string;
     laneId?: string;
+    cleanupHandle?: SubtreeSpawnLaunchHandle;
 }
 export interface PinetSubtreeSpawnResult {
     status: "started";
     launchId: string;
+    runtimeKind: "tmux" | "herdr";
     sessionName: string;
     repoPath: string;
     role: string;
@@ -47,6 +51,7 @@ export interface PinetSubtreeSpawnResult {
     childLaunchEnv: Record<string, string>;
 }
 export interface RegisterPinetToolsDeps {
+    promptGuidelines?: string[];
     pinetEnabled: () => boolean;
     brokerRole: () => "broker" | "follower" | null;
     requireToolPolicy: (toolName: string, threadTs: string | undefined, action: string) => void;
@@ -97,6 +102,15 @@ export interface RegisterPinetToolsDeps {
         reason?: string | null;
     }) => RalphSnoozeStatus;
     clearRalphSnooze?: () => RalphSnoozeStatus;
+    runHibernateCommand?: (input: {
+        target: string;
+        reason?: string;
+    }) => Promise<HibernationCommandResult>;
+    runWakeCommand?: (input: {
+        target: string;
+        reason?: string;
+    }) => Promise<HibernationCommandResult>;
+    getAgentLifecycleProjection?: (agentIds?: string[]) => AgentLifecycleStatus[];
 }
 type PinetDispatcherStatus = "succeeded" | "failed";
 interface PinetRenderContentBlock {