@pinet/slack-bridge 0.2.2 → 0.2.6

package/dist/broker/hibernation-runtime-helpers.js

@@ -0,0 +1,243 @@
+// Pure, side-effect-free helpers for the live hibernation runtime adapters.
+//
+// These back the real `HibernationProcessController` / `HibernationTmuxController`
+// (which shell out to `ps`, `kill`, `git`, and `tmux`) and the worker-side wake
+// fence ingestion. Keeping the string/parse logic pure makes the security- and
+// correctness-critical pieces (VCS identity derivation, wake-fence env parsing,
+// resume-launcher construction) unit-testable without spawning processes.
+import { parsePinetStableId } from "../pinet-session-formatting.js";
+/** Single-quote a value for safe embedding in a POSIX shell launcher script. */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Derive a canonical `owner/repo` VCS identity from a git remote URL. Supports
+ * scp-style (`git@github.com:owner/repo.git`), URL (`https://host/owner/repo`,
+ * `ssh://git@host/owner/repo`, `git://host/owner/repo`), and bare `owner/repo`
+ * forms. Returns null when no `owner/repo` can be derived.
+ *
+ * This is the ONLY identity the repo allowlist authorizes against, and it is
+ * derived from the runtime's actual git REMOTE — never from filesystem directory
+ * names — so distinct roots that merely share their final path segments (or a
+ * worktree vs. its clone) never collapse onto, or diverge from, one authorization
+ * identity.
+ */
+export function deriveVcsIdentity(remoteUrl) {
+    const raw = remoteUrl?.trim();
+    if (!raw)
+        return null;
+    // Normalize: drop a trailing `.git` and any trailing slashes.
+    const normalized = raw.replace(/\.git$/i, "").replace(/\/+$/, "");
+    let pathPart = null;
+    const scp = /^[^@\s/]+@[^:\s/]+:(.+)$/.exec(normalized); // git@host:owner/repo
+    const url = /^[a-z][a-z0-9+.-]*:\/\/[^/]+\/(.+)$/i.exec(normalized); // scheme://host/owner/repo
+    if (scp) {
+        pathPart = scp[1];
+    }
+    else if (url) {
+        pathPart = url[1];
+    }
+    else if (normalized.includes("/") && !normalized.includes(":")) {
+        pathPart = normalized; // bare owner/repo (or deeper path)
+    }
+    if (!pathPart)
+        return null;
+    const segments = pathPart.split("/").filter(Boolean);
+    if (segments.length < 2)
+        return null;
+    const owner = segments[segments.length - 2];
+    const repo = segments[segments.length - 1];
+    if (!owner || !repo)
+        return null;
+    return `${owner}/${repo}`;
+}
+/**
+ * Parse resident set size (bytes) from `ps -o rss= -p <pid>` output. macOS/Linux
+ * `ps` reports RSS in kibibytes; returns null when no numeric value is present
+ * (e.g. the process already exited).
+ */
+export function parseRssBytesFromPs(psOutput) {
+    const match = /\d+/.exec(psOutput ?? "");
+    if (!match)
+        return null;
+    const kib = Number.parseInt(match[0], 10);
+    return Number.isFinite(kib) ? kib * 1024 : null;
+}
+/**
+ * Build the broker-resolvable, redaction-safe session resume reference for a
+ * worker from its stable id. A worker's stable id embeds the absolute path to
+ * its Pi session `.jsonl` (`<host>:session:<path>`); the resume ref is stored as
+ * `session:<path>` so `redactRuntimeSpec` digests it to `session:#<fingerprint>`
+ * on every operator/JSON surface while the broker can still recover the path to
+ * respawn `pi --session <path>`. Returns null for stable ids without a session
+ * path (e.g. `cwd:`/`leaf:` kinds), which are not resumable.
+ */
+export function sessionResumeRefFromStableId(stableId) {
+    const parsed = parsePinetStableId(stableId);
+    // Only the `session` kind carries a resumable Pi session `.jsonl`; `cwd`/`leaf`
+    // stable ids also expose a filesystem locator but have no resumable session.
+    if (!parsed || parsed.kind !== "session" || !parsed.hasPath)
+        return null;
+    return `session:${parsed.locator}`;
+}
+/** Recover the absolute session `.jsonl` path from a `session:<path>` resume ref. */
+export function resumePathFromSessionRef(sessionResumeRef) {
+    const ref = sessionResumeRef?.trim();
+    if (!ref)
+        return null;
+    const separator = ref.indexOf(":");
+    if (separator <= 0)
+        return null;
+    if (ref.slice(0, separator) !== "session")
+        return null;
+    const path = ref.slice(separator + 1).trim();
+    return path.length > 0 ? path : null;
+}
+/**
+ * Environment variables the respawn launcher exports so the woken runtime can
+ * present its single-use wake fence on registration. Ordinary (non-wake) spawns
+ * never set these, so ordinary registration stays fence-free and backward
+ * compatible.
+ */
+export function buildWakeFenceEnv(input) {
+    return {
+        PINET_WAKE_LEASE_ID: input.wakeLeaseId,
+        PINET_WAKE_FENCE_TOKEN: String(input.fenceToken),
+        PINET_WAKE_RESERVED_GENERATION: String(input.reservedGeneration),
+        PINET_WAKE_RESERVATION_NONCE: input.reservationNonce,
+        PINET_WAKE_CORRELATION_ID: input.correlationId,
+    };
+}
+/**
+ * Parse a canonical positive decimal safe integer, or null. Unlike
+ * `Number.parseInt`, which silently coerces `"12abc"`→12, `" 12"`→12, `"+12"`→12
+ * and accepts leading-zero forms, this accepts ONLY a bare run of decimal digits
+ * with no sign, no leading zero, no surrounding whitespace, and a value within
+ * the safe-integer range. A garbled or hostile fence value therefore fails
+ * closed to an ordinary (fence-free) registration rather than silently
+ * round-tripping a corrupted generation/token.
+ */
+function parseCanonicalPositiveInt(raw) {
+    if (raw == null || !/^[1-9][0-9]*$/.test(raw))
+        return null;
+    const value = Number(raw);
+    return Number.isSafeInteger(value) ? value : null;
+}
+/**
+ * Parse a wake fence from a woken worker's environment (the boundary between the
+ * respawn launcher and the follower's register RPC). Returns null unless ALL
+ * required fields are present and well-formed — the numeric fence token and
+ * reserved generation must be canonical positive decimal safe integers — so a
+ * partial/garbled environment fails closed to an ordinary (fence-free)
+ * registration rather than a malformed fenced one.
+ */
+export function parseWakeFenceEnv(env) {
+    const wakeLeaseId = env.PINET_WAKE_LEASE_ID?.trim();
+    const reservationNonce = env.PINET_WAKE_RESERVATION_NONCE?.trim();
+    const fenceToken = parseCanonicalPositiveInt(env.PINET_WAKE_FENCE_TOKEN);
+    const reservedGeneration = parseCanonicalPositiveInt(env.PINET_WAKE_RESERVED_GENERATION);
+    if (!wakeLeaseId || !reservationNonce)
+        return null;
+    if (fenceToken == null || reservedGeneration == null)
+        return null;
+    return { wakeLeaseId, fenceToken, reservedGeneration, reservationNonce };
+}
+/**
+ * Compose a durable {@link AgentRuntimeSpecInput} from broker-known spawn facts.
+ *
+ * Fails closed (returns null) when the identity is not a resumable Pi session
+ * (`sessionResumeRef` cannot be derived) or any operational locator the broker
+ * must act on (tmux socket/session/target, repo root) is missing — a spec that
+ * could not be safely hibernated/woken is never recorded. `expectedHost` is
+ * taken from the stable id's host prefix; `argv` mirrors the resume launch
+ * (`pi -e <entry> --session <path>`) for provenance; the resume path itself is
+ * only ever recovered from the redaction-safe `sessionResumeRef`.
+ */
+export function buildRuntimeSpecInput(facts) {
+    const sessionResumeRef = sessionResumeRefFromStableId(facts.stableId);
+    if (!sessionResumeRef)
+        return null;
+    const resumePath = resumePathFromSessionRef(sessionResumeRef);
+    if (!resumePath || !facts.repoRoot)
+        return null;
+    const common = {
+        agentId: facts.agentId,
+        stableId: facts.stableId,
+        brokerOwnerId: facts.brokerOwnerId,
+        cwd: facts.cwd || facts.repoRoot,
+        repoRoot: facts.repoRoot,
+        worktreePath: facts.worktreePath || facts.repoRoot,
+        executable: "pi",
+        argv: ["-e", facts.extensionEntryPath, "--session", resumePath],
+        envAllowlist: Array.from(new Set(facts.envAllowlist.filter((name) => name.length > 0))),
+        sessionResumeRef,
+        configFingerprint: facts.configFingerprint || "unknown",
+        expectedHost: parsePinetStableId(facts.stableId)?.host ?? "",
+        expectedUser: facts.expectedUser,
+        launchSource: facts.launchSource || "subtree-broker-tmux",
+        vcsIdentity: facts.vcsIdentity,
+    };
+    if (facts.runtimeKind === "herdr") {
+        if (!facts.herdrSession ||
+            !facts.herdrConfigDir ||
+            !facts.herdrPaneId ||
+            !Number.isInteger(facts.herdrShellPid) ||
+            facts.herdrShellPid <= 0) {
+            return null;
+        }
+        return {
+            ...common,
+            runtimeKind: "herdr",
+            herdrSession: facts.herdrSession,
+            herdrConfigDir: facts.herdrConfigDir,
+            herdrPaneId: facts.herdrPaneId,
+            herdrShellPid: facts.herdrShellPid,
+        };
+    }
+    if (!facts.tmuxSocket || !facts.tmuxSession || !facts.tmuxTarget)
+        return null;
+    return {
+        ...common,
+        runtimeKind: "tmux",
+        tmuxSocket: facts.tmuxSocket,
+        tmuxSession: facts.tmuxSession,
+        tmuxTarget: facts.tmuxTarget,
+    };
+}
+/**
+ * Build the launcher script a wake attempt runs via `tmux respawn-pane` to bring
+ * back the fenced runtime. It re-establishes the repo cwd and launch environment,
+ * exports the wake fence, and resumes the exact session with `pi --session
+ * <path>` (no startup prompt — the session already carries the worker's context;
+ * injecting a prompt would append a spurious user turn). The woken Pi therefore
+ * re-registers under the SAME stable id (same session path) and presents the
+ * fence for atomic generation acceptance.
+ *
+ * The script is secret-bearing (it exports mesh/Slack credential VALUES), so it
+ * removes its own file (`rm -f -- "$0"`) as its FIRST executable action — before
+ * `cd` and before exporting ANY secret. Under `set -euo pipefail` a later failure
+ * (e.g. a missing/unmounted repo making `cd` exit) therefore cannot leave a
+ * secret-bearing file behind, closing the “tmux accepted launch, launcher began,
+ * pre-delete setup failed” retention window. The launcher fd stays open across the
+ * unlink (POSIX keeps the inode until the fd closes), so `exec pi` still runs from
+ * the now-unnamed inode even though the secrets are exported after the unlink. The
+ * broker separately unlinks on the failure path (where the script never ran) and
+ * materializes launchers only in a private, owner-only directory.
+ */
+export function buildResumeLauncherScript(input) {
+    // Self-delete FIRST (before cd and before any secret export) so no failure in
+    // the remaining setup can leave the secret-bearing launcher on disk.
+    const lines = ["#!/bin/bash", "set -euo pipefail", `rm -f -- "$0"`];
+    lines.push(`cd ${shellQuote(input.repoPath)}`);
+    for (const [key, value] of Object.entries(input.inheritedEnv)) {
+        if (value !== undefined && value !== "")
+            lines.push(`export ${key}=${shellQuote(value)}`);
+    }
+    for (const [key, value] of Object.entries(input.pinetEnv)) {
+        lines.push(`export ${key}=${shellQuote(value)}`);
+    }
+    lines.push(`export PI_NICKNAME=${shellQuote(input.nickname)}`);
+    lines.push(`exec pi -e ${shellQuote(input.extensionEntryPath)} --session ${shellQuote(input.sessionPath)}`);
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/broker/index.d.ts

@@ -5,7 +5,10 @@ import { LeaderLock } from "./leader.js";
 import type { MessageAdapter } from "./types.js";
 export { BrokerDB } from "./schema.js";
 export { BrokerSocketServer } from "./socket-server.js";
-export { LeaderLock } from "./leader.js";
+export { LeaderLock, inspectBrokerLock, readBrokerLockOwner, getProcessStartTime, } from "./leader.js";
+export type { BrokerLockInspection, BrokerLockOwner, BrokerLockProbes } from "./leader.js";
+export { BrokerLockConflictError, classifyBrokerLockConflict, formatBrokerLockConflictMessage, probeBrokerSocket, replaceBrokerOwner, requestBrokerShutdown, } from "./lock-conflict.js";
+export type { BrokerLockConflict, BrokerLockConflictClassification, BrokerShutdownRequestResult, BrokerSocketProbeResult, ReplaceBrokerOwnerOptions, ReplaceBrokerOwnerOutcome, ReplaceBrokerOwnerResult, } from "./lock-conflict.js";
 export type { ListenTarget } from "./socket-server.js";
 export type { AgentMessageCallback, AgentRegistrationResolver } from "./socket-server.js";
 export type { AgentInfo, ThreadInfo, ScheduledWakeupInfo, ScheduledWakeupDelivery, BrokerMessage, InboxEntry, InboundMessage, OutboundMessage, AdapterCapabilityRequest, AdapterCapabilityResult, MessageAdapter, JsonRpcRequest, JsonRpcResponse, TaskAssignmentInfo, TaskAssignmentStatus, } from "./types.js";
@@ -18,6 +21,17 @@ export interface BrokerOptions {
     lockPath?: string;
     meshSecret?: string;
     meshSecretPath?: string;
+    /**
+     * Runs after DB initialization but BEFORE the socket server begins listening
+     * (i.e. before any client can connect or register). Use for startup
+     * reconciliation — e.g. stranded-wake recovery — that must deterministically
+     * complete before an incoming registration can race it. If it throws, the
+     * broker is torn down (DB closed, lock released) and the error propagates so a
+     * failed reconciliation never leaves a half-open, already-listening broker.
+     */
+    beforeListen?: (ctx: {
+        db: BrokerDB;
+    }) => void | Promise<void>;
 }
 export interface Broker {
     db: BrokerDB;
@@ -25,6 +39,7 @@ export interface Broker {
     lock: LeaderLock;
     adapters: MessageAdapter[];
     addAdapter(adapter: MessageAdapter): void;
+    removeAdapters(adapters: readonly MessageAdapter[]): Promise<void>;
     stop(): Promise<void>;
 }
 /**

package/dist/broker/index.js

@@ -4,10 +4,12 @@ import { loadOrCreateMeshSecret } from "./auth.js";
 import { BrokerSocketServer } from "./socket-server.js";
 import { assertLoopbackTcpHost } from "./raw-tcp-loopback.js";
 import { LeaderLock } from "./leader.js";
+import { BrokerLockConflictError, classifyBrokerLockConflict } from "./lock-conflict.js";
 import { getDefaultSocketPath } from "./paths.js";
 export { BrokerDB } from "./schema.js";
 export { BrokerSocketServer } from "./socket-server.js";
-export { LeaderLock } from "./leader.js";
+export { LeaderLock, inspectBrokerLock, readBrokerLockOwner, getProcessStartTime, } from "./leader.js";
+export { BrokerLockConflictError, classifyBrokerLockConflict, formatBrokerLockConflictMessage, probeBrokerSocket, replaceBrokerOwner, requestBrokerShutdown, } from "./lock-conflict.js";
 /**
  * Start the broker: acquire leader lock, initialize SQLite, start the Unix socket server.
  * Only one broker may run at a time — enforced by a PID lock file.
@@ -24,9 +26,29 @@ export async function startBroker(options = {}) {
         assertLoopbackTcpHost(target.host, "broker listen target");
     }
     // ── Leader lock: prevent split-brain (issue #119) ────
+    // On conflict, classify the lock owner (issue #951) so callers can offer a
+    // real recovery path instead of a generic failure.
     const lock = new LeaderLock(options.lockPath);
     if (!lock.tryAcquire()) {
-        throw new Error("Another pinet broker is already running. Only one broker may be active at a time.");
+        const conflict = await classifyBrokerLockConflict({
+            lockPath: lock.getLockPath(),
+            target,
+        });
+        // The owner may have died between the acquire attempt and classification
+        // — retry once when the conflict became reclaimable.
+        if (conflict.kind === "reclaimable" && lock.tryAcquire()) {
+            // Raced a dying owner; we now hold the lock.
+        }
+        else if (conflict.kind === "conflict") {
+            throw new BrokerLockConflictError({
+                classification: conflict.classification,
+                owner: conflict.owner,
+                probe: conflict.probe,
+            });
+        }
+        else {
+            throw new Error("Another pinet broker is already running. Only one broker may be active at a time.");
+        }
     }
     const db = new BrokerDB(options.dbPath);
     try {
@@ -53,6 +75,19 @@ export async function startBroker(options = {}) {
     const server = new BrokerSocketServer(db, target, {
         ...(resolvedMeshSecret ? { meshSecret: resolvedMeshSecret } : {}),
     });
+    // Run startup reconciliation strictly BEFORE the socket opens, so nothing can
+    // connect/register until it completes. A failure here must not leave a
+    // half-open broker: tear down before rethrowing (the server has not started).
+    if (options.beforeListen) {
+        try {
+            await options.beforeListen({ db });
+        }
+        catch (err) {
+            db.close();
+            lock.release();
+            throw err;
+        }
+    }
     try {
         await server.start();
     }
@@ -71,19 +106,42 @@ export async function startBroker(options = {}) {
             adapters.push(adapter);
             server.setOutboundMessageAdapters(adapters);
         },
-        async stop() {
-            for (const adapter of adapters) {
+        async removeAdapters(removedAdapters) {
+            const removed = new Set(removedAdapters);
+            const retained = adapters.filter((adapter) => !removed.has(adapter));
+            adapters.length = 0;
+            adapters.push(...retained);
+            server.setOutboundMessageAdapters(adapters);
+            const disconnectErrors = [];
+            for (const adapter of removedAdapters) {
                 try {
                     await adapter.disconnect();
                 }
-                catch {
-                    // best effort
+                catch (error) {
+                    disconnectErrors.push(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+            if (disconnectErrors.length > 0) {
+                throw new AggregateError(disconnectErrors, "Failed to disconnect broker adapters");
+            }
+        },
+        async stop() {
+            try {
+                await this.removeAdapters([...adapters]);
+            }
+            finally {
+                try {
+                    await server.stop();
+                }
+                finally {
+                    try {
+                        db.close();
+                    }
+                    finally {
+                        lock.release();
+                    }
                 }
             }
-            adapters.length = 0;
-            await server.stop();
-            db.close();
-            lock.release();
         },
     };
     return broker;

package/dist/broker/lock-conflict.d.ts

@@ -0,0 +1,109 @@
+import { type BrokerLockInspection, type BrokerLockOwner, type BrokerLockProbes } from "./leader.js";
+import type { ListenTarget } from "./socket-server.js";
+export declare const DEFAULT_PROBE_TIMEOUT_MS = 2000;
+export declare const DEFAULT_SHUTDOWN_RPC_TIMEOUT_MS = 5000;
+export declare const DEFAULT_GRACEFUL_WAIT_MS = 8000;
+export declare const DEFAULT_TERMINATE_WAIT_MS = 8000;
+export declare const DEFAULT_REPLACE_POLL_INTERVAL_MS = 250;
+export type BrokerSocketProbeResult = "healthy" | "unreachable" | "unresponsive";
+export interface ProbeBrokerSocketOptions {
+    target?: ListenTarget;
+    socketPath?: string;
+    timeoutMs?: number;
+}
+/**
+ * Bounded liveness probe for a broker socket. Any well-formed JSON-RPC
+ * response — including an auth error — proves the broker event loop is
+ * serving, so it classifies as healthy.
+ */
+export declare function probeBrokerSocket(options?: ProbeBrokerSocketOptions): Promise<BrokerSocketProbeResult>;
+export type BrokerShutdownRequestResult = "accepted"
+/** The broker responded with method-not-found — it predates the RPC. */
+ | "unsupported"
+/** The broker responded with an error (e.g. auth rejection) — it is alive and refusing. */
+ | "rejected" | "unreachable"
+/** Connected but no usable response — the broker looks hung. */
+ | "failed";
+export interface RequestBrokerShutdownOptions {
+    target?: ListenTarget;
+    socketPath?: string;
+    meshSecret?: string | null;
+    timeoutMs?: number;
+}
+/**
+ * Ask a running broker to shut down gracefully via the authenticated
+ * `admin.shutdown` RPC. Brokers that predate the RPC report `unsupported`.
+ */
+export declare function requestBrokerShutdown(options?: RequestBrokerShutdownOptions): Promise<BrokerShutdownRequestResult>;
+export type BrokerLockConflictClassification = "active-broker" | "unresponsive-broker";
+export type BrokerLockConflict = {
+    kind: "reclaimable";
+    inspection: BrokerLockInspection;
+    probe: null;
+} | {
+    kind: "conflict";
+    classification: BrokerLockConflictClassification;
+    owner: BrokerLockOwner;
+    probe: BrokerSocketProbeResult;
+};
+export interface ClassifyBrokerLockConflictOptions {
+    lockPath?: string;
+    target?: ListenTarget;
+    socketPath?: string;
+    probeTimeoutMs?: number;
+    probes?: BrokerLockProbes;
+    probeSocket?: (target: ListenTarget, timeoutMs: number) => Promise<BrokerSocketProbeResult>;
+}
+/**
+ * Combine lock-owner inspection with a bounded socket probe to classify a
+ * leader-lock conflict.
+ */
+export declare function classifyBrokerLockConflict(options?: ClassifyBrokerLockConflictOptions): Promise<BrokerLockConflict>;
+export interface BrokerLockConflictErrorInput {
+    classification: BrokerLockConflictClassification;
+    owner: BrokerLockOwner | null;
+    probe: BrokerSocketProbeResult | null;
+}
+export declare function formatBrokerLockConflictMessage(input: BrokerLockConflictErrorInput): string;
+/**
+ * Thrown by `startBroker` when the leader lock is held by another live
+ * process, carrying enough context for callers to present a per-state
+ * recovery path instead of a generic failure.
+ */
+export declare class BrokerLockConflictError extends Error {
+    readonly classification: BrokerLockConflictClassification;
+    readonly owner: BrokerLockOwner | null;
+    readonly probe: BrokerSocketProbeResult | null;
+    constructor(input: BrokerLockConflictErrorInput);
+}
+export type ReplaceBrokerOwnerOutcome = "no-conflict" | "replaced-graceful" | "replaced-terminated" | "owner-changed" | "failed";
+export interface ReplaceBrokerOwnerResult {
+    outcome: ReplaceBrokerOwnerOutcome;
+    owner: BrokerLockOwner | null;
+    steps: string[];
+    error: string | null;
+}
+export interface ReplaceBrokerOwnerOptions {
+    lockPath?: string;
+    target?: ListenTarget;
+    socketPath?: string;
+    meshSecret?: string | null;
+    gracefulWaitMs?: number;
+    terminateWaitMs?: number;
+    pollIntervalMs?: number;
+    shutdownRpcTimeoutMs?: number;
+    probes?: BrokerLockProbes;
+    requestShutdown?: (options: RequestBrokerShutdownOptions) => Promise<BrokerShutdownRequestResult>;
+    kill?: (pid: number, signal: NodeJS.Signals) => void;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Conservatively replace the current broker lock owner:
+ *
+ * 1. No live owner → nothing to do (a normal start reclaims stale state).
+ * 2. Live owner → request graceful `admin.shutdown` and wait (bounded).
+ * 3. Fallback → re-verify the owner fence (pid + process start time +
+ *    instance id), SIGTERM the verified owner, and wait (bounded).
+ * 4. Never SIGKILL; abort if the owner identity changes mid-flight.
+ */
+export declare function replaceBrokerOwner(options?: ReplaceBrokerOwnerOptions): Promise<ReplaceBrokerOwnerResult>;