@essentialai/cogent-bridge 3.23.3 → 3.23.4

package/dist/services/wake-ownership.js

@@ -0,0 +1,193 @@
+/**
+ * WAKE OWNERSHIP — a superseded bridge process stops waking, by itself, with nobody running pkill.
+ *
+ * ── WHY (operator, 2026-09-05) ───────────────────────────────────────────────────────────
+ * "killed, but my users dont do that - so think how to have self healing mechanism"
+ *
+ * ── WHAT IS ACTUALLY ON A REAL MACHINE (measured here, 2026-09-05) ───────────────────────
+ * 37 live cogent-bridge processes, and NOT ONE of them is an orphan — every parent is alive:
+ *
+ *   codex app-server (1 daemon, up 3.5 days) ......... 7 bridges, all at a stale 3.22.0
+ *   claude --resume <one interactive session> ........ 2 bridges (plugin AND an npx @latest)
+ *   5 other interactive `claude --resume` sessions ... 1 each
+ *
+ * That kills the obvious fix. "Exit when stdin hits EOF" heals nothing here, because no bridge has
+ * lost its parent. They are not orphaned, they are REDUNDANT: a long-lived daemon spawns a bridge
+ * per MCP session and never reaps them, and one agent session can have cogent registered twice.
+ * A plugin update does not stop any of them, so old versions keep serving for days.
+ *
+ * ── THE SIGNAL: SAME peerId, NOT same cwd ────────────────────────────────────────────────
+ * Superseding on cwd alone would break a legitimate setup — two agents working one checkout (say
+ * `marvin-coder` and `marvin-mobile`) are two DIFFERENT peers and both must keep waking. What is
+ * never legitimate is the same peerId served by two bridges in one checkout: that is the ghost,
+ * and it is exactly what was measured on the real user (`marvin-coder` live on the FREE relay at
+ * v3.20.0 and on the TEAM relay at v3.23.1, same cwd, same thread).
+ *
+ * So ownership is keyed on (cwd, peerId). The wake LOCK (wake-lock.ts) stays keyed on cwd alone,
+ * because worktree corruption does not care which peer caused it. Two invariants, two keys:
+ *   ownership → only ONE process does this peer's work   (kills duplicate work)
+ *   lock      → only ONE turn runs in this checkout      (kills concurrent corruption)
+ *
+ * ── NEWEST WINS, BY PROCESS START, SO IT CANNOT OSCILLATE ────────────────────────────────
+ * The owner is the live bridge with the latest PROCESS START time. Start time is fixed for the
+ * life of a process, so a superseded bridge can never win the title back — if ownership were keyed
+ * on registration time instead, a stood-down bridge that re-registered would steal it back and the
+ * two would ping-pong forever.
+ *
+ * ── ONE FILE PER PID, SO THERE IS NO WRITE RACE ──────────────────────────────────────────
+ * Each process writes ONLY its own `<pid>.json`; nobody rewrites a shared document, so concurrent
+ * registration cannot corrupt or lose an entry. Reading is a readdir plus a liveness check, and
+ * dead entries are pruned opportunistically by whoever notices them.
+ *
+ * ── FAILS OPEN ───────────────────────────────────────────────────────────────────────────
+ * Any unreadable/unwritable state resolves to "you are the owner, go ahead and wake". A
+ * self-healing mechanism that can silence a healthy agent is a worse bug than the one it heals —
+ * that is the 3.21.5 lesson, where a fix took auto-wake down for every default-config macOS user.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { logger } from "../logger.js";
+/**
+ * When this process started. Captured at module load — as close to process start as we can get
+ * from inside — and never recomputed, which is what makes ownership stable and non-oscillating.
+ */
+const PROCESS_STARTED_AT = Date.now() - Math.floor(process.uptime() * 1000);
+/** MUST match wake-lock / wake-claim / credential-store — one cwd, one key, everywhere. */
+function hashCwd(cwd) {
+    return crypto.createHash("sha256").update(path.resolve(cwd)).digest("hex").slice(0, 16);
+}
+const safe = (s) => String(s).replace(/[^A-Za-z0-9._-]/g, "_");
+/** `~/.cogent/bridges/<sha256(cwd)[..16]>.<peerId>/` — one directory per identity. */
+export function bridgeDirFor(cwd, peerId) {
+    return path.join(os.homedir(), ".cogent", "bridges", `${hashCwd(cwd)}.${safe(peerId)}`);
+}
+/** Is that pid a live process? Unknown/odd values count as DEAD so their entries get pruned. */
+function pidAlive(pid) {
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    if (pid === process.pid)
+        return true;
+    try {
+        process.kill(pid, 0); // signal 0 = existence check only
+        return true;
+    }
+    catch (err) {
+        // EPERM means it EXISTS but belongs to another user — alive for our purposes.
+        return err?.code === "EPERM";
+    }
+}
+/**
+ * Announce this process as a bridge serving `peerId` in `cwd`.
+ *
+ * Called once the peer is actually registered, so a bridge that never registered never competes
+ * for ownership. Best-effort: a failure here leaves us un-announced, which can only make us LOSE
+ * ownership to someone else, never wrongly take it.
+ */
+export function announceBridge(cwd, peerId, version, endpoint) {
+    const dir = bridgeDirFor(cwd, peerId);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        const entry = {
+            pid: process.pid,
+            startedAt: PROCESS_STARTED_AT,
+            version,
+            peerId,
+            endpoint,
+            cwd: path.resolve(cwd),
+        };
+        fs.writeFileSync(path.join(dir, `${process.pid}.json`), JSON.stringify(entry));
+    }
+    catch (err) {
+        logger.debug(`wake-ownership: could not announce this bridge (${err.message})`);
+    }
+}
+/** Remove this process's announcement. Called on graceful shutdown; a crash is handled by pruning. */
+export function withdrawBridge(cwd, peerId) {
+    try {
+        fs.unlinkSync(path.join(bridgeDirFor(cwd, peerId), `${process.pid}.json`));
+    }
+    catch {
+        /* already gone, or never announced */
+    }
+}
+/**
+ * Every LIVE bridge announced for this identity, newest process first.
+ *
+ * Prunes entries whose process is gone, so a machine that has been through a dozen plugin updates
+ * does not accumulate junk here forever.
+ */
+export function listLiveBridges(cwd, peerId) {
+    const dir = bridgeDirFor(cwd, peerId);
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return []; // no directory = nobody announced = no competition
+    }
+    const live = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const p = path.join(dir, name);
+        let entry = null;
+        try {
+            entry = JSON.parse(fs.readFileSync(p, "utf-8"));
+        }
+        catch {
+            entry = null;
+        }
+        if (!entry || !pidAlive(entry.pid) || typeof entry.startedAt !== "number") {
+            try {
+                fs.unlinkSync(p); // prune: the process is gone or the record is unusable
+            }
+            catch {
+                /* raced with another pruner */
+            }
+            continue;
+        }
+        live.push(entry);
+    }
+    // Newest process first; pid breaks a same-millisecond tie deterministically so every process
+    // computes the SAME owner. A non-deterministic tie-break would let two bridges each believe
+    // they own it — the exact condition this exists to prevent.
+    live.sort((a, b) => b.startedAt - a.startedAt || b.pid - a.pid);
+    return live;
+}
+/**
+ * Should THIS process wake for `peerId` in `cwd`?
+ *
+ * No when a strictly newer live bridge serves the same identity — that bridge is the one the user
+ * most recently started, and we are the leftover.
+ */
+export function checkWakeOwnership(cwd, peerId) {
+    let live;
+    try {
+        live = listLiveBridges(cwd, peerId);
+    }
+    catch (err) {
+        logger.warn(`wake-ownership: could not read bridge registry (${err.message}) — assuming ownership`);
+        return { isOwner: true, liveCount: 1 };
+    }
+    // Nobody announced (including us — announcement is best-effort): assume ownership. Standing
+    // down on missing evidence would mute a healthy, solitary agent.
+    if (live.length === 0)
+        return { isOwner: true, liveCount: 0 };
+    const owner = live[0];
+    if (owner.pid === process.pid)
+        return { isOwner: true, liveCount: live.length };
+    // We are announced but are not newest -> superseded.
+    if (live.some((e) => e.pid === process.pid)) {
+        return {
+            isOwner: false,
+            owner: { pid: owner.pid, version: owner.version, endpoint: owner.endpoint },
+            liveCount: live.length,
+        };
+    }
+    // Others are announced but we are not (our own announce failed). Do NOT stand down on the
+    // strength of a record we could not write: fail open.
+    return { isOwner: true, liveCount: live.length + 1 };
+}
+//# sourceMappingURL=wake-ownership.js.map

package/dist/services/wake-ownership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake-ownership.js","sourceRoot":"","sources":["../../src/services/wake-ownership.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@essentialai/cogent-bridge",
-  "version": "3.23.3",
+  "version": "3.23.4",
   "description": "Cogent Bridge — cross-agent comms for Claude Code, OpenAI Codex and Slack. Codex users: install with `curl -fsSL https://cogent.tools/install.sh | sh`, then start with `cogent-codex` for real-time peer wake.",
   "type": "module",
   "workspaces": [

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.eaisdevelopment/cogent",
   "title": "Cogent Bridge from Essential AI Solutions (essentialai.uk)",
   "description": "MCP bridge for inter-session communication between Claude Code instances",
-  "version": "3.23.3",
+  "version": "3.23.4",
   "repository": {
     "url": "https://github.com/eaisdevelopment/cogent",
     "source": "github"
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "@essentialai/cogent-bridge",
-      "version": "3.23.3",
+      "version": "3.23.4",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"