@essentialai/cogent-bridge 3.23.9 → 3.24.1

package/CHANGELOG.md

@@ -1,3 +1,112 @@
+## 3.24.1 — 2026-09-15
+
+Patch release. One product fix, one user-facing discoverability fix, and three gate fixes — every
+one of them a case of a check reporting something that was not true.
+
+### `cogent_register_peer` could never auto-create a channel (product)
+
+Registering with **no channel configured** — the zero-config onboarding path — has never worked.
+The client posted `` label: `Auto-created by ${label}` `` while the relay's own
+`CreateSessionRequestSchema` requires `/^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$/`: lowercase, digits and
+hyphens. A capital `A` and spaces cannot match, so every auto-create returned **HTTP 400
+INVALID_INPUT**. Measured against a real relay:
+
+```
+{ secret, label: "Auto-created by Payment Orchestrator" } -> 400 invalid_format
+{ secret }                                                -> 201  label "slim-tap-27be"
+```
+
+The 400 was visible as far back as 3.5.2 and was read as "avoid falling into auto-create", so the
+symptom was routed around while the path stayed broken. Fixed by omitting the label and letting the
+relay name the channel — it already does so with collision-retry scoped to the org. The generated
+label is now persisted so a human can learn which channel to join.
+
+### Slash commands say what input they expect
+
+`/cogent:register` parses a channel name, a password, a peer name and an optional ORGID out of free
+text, and falls back to the project `.env` when given nothing. None of that was discoverable: the
+picker showed only a description. All commands that parse `$ARGUMENTS` now declare `argument-hint`:
+
+```
+/cogent:register [channel "<name>" password "<pw>" peer "<peerId>" [ORGID "<org-id>"]] — omit to use .env
+/cogent:send     [peerId] [message] — omit to pick from the peer list
+/cogent:init     [<project-path> <project-path> ...] [--share <shared-path>]
+```
+
+### Gates: three false verdicts fixed
+
+- **An unanswered `--human-inbound` window is BLOCKED, not a product break.** When nobody typed the
+  line, the harness printed `PRODUCT FAILURES ❌ … customer-visible Slack regression` and exited 1
+  — a regression claimed out of an empty chair. Now stamped with a `NO_HUMAN_INPUT` code and
+  classified first, so it exits 2 ("proves nothing"). The adjacent real failure — Slack seeing the
+  message while the adapter drops it — is asserted to stay exit 1.
+- **Harnesses target the SANDBOX by default.** Seven of them hardcoded
+  `argVal("--endpoint", "https://cogent.tools")`, so running the tests was indistinguishable from
+  exercising production. `scripts/target-lib.mjs` is now the single source of truth, production is
+  an explicit `--target prod`, and an unreachable target BLOCKS rather than degrading — there is
+  deliberately no fallback. This immediately exposed `wake-race-test`, which was labelled
+  `runnable_offline: true` while silently POSTing to the production relay on every run; it now uses
+  the local relay rig.
+- **Per-agent vendor liveness preflight** (`scripts/vendor-liveness-test.mjs`). Asks each vendor
+  whether it is alive **through the product's own spawn path** before a matrix burns an hour
+  proving the same thing. Exit 2 on a dead vendor, never 1: an expired quota is not a Cogent defect.
+
+### Unchanged
+
+No wire-format change. No relay behaviour change beyond the advertised plugin version.
+## 3.24.0 — 2026-09-14
+
+### An agent knows whether it is IN its channel — and puts itself back
+
+**The defect.** Registration is an explicit act: something must call `cogent_register_peer`. A
+bridge starting does NOT register — it only publishes the tools. So an agent session could come up
+holding valid credentials while being ABSENT from its own channel, invisible to everyone messaging
+it. That state was silent AND self-perpetuating, because every repair sat behind a successful
+registration:
+
+- `announceBridge()` — written at register time
+- `reapStaleBridges()` — "only after a peer is genuinely registered"
+- `triggerReRegistration()` — reads in-memory state, which is null in a fresh process
+
+When registration was the thing that did not happen, nothing recovered and nothing cleaned up.
+Measured on one checkout: **18 live bridges at 3.23.9**, only 2 announcements (both dead pids), last
+successful register five days earlier, and the peer absent from a healthy Team channel whose two
+other agents were present and waiting on it.
+
+**Presence**, in the vocabulary this codebase already used:
+
+| state | meaning |
+|---|---|
+| `local` | no relay; presence does not apply |
+| `deferred` | cloud-configured, never joined |
+| `offline` | owns a peer for this cwd but has not registered it — nobody can reach it |
+| `online` | registered; the channel lists this agent |
+
+Evaluated once at startup, fire-and-forget after the transport connects, and **reported**:
+`offline -> online` at INFO, a stuck `offline` at WARN. `cogent_health_check` now carries
+`presence`, so an agent can ASK its own state instead of inferring it from transport internals.
+
+- **`COGENT_AUTO_PRESENCE`** (default ON) — set `false` to observe the state without acting on it.
+- **`cogent_deregister_peer` now clears the stored `peerId`.** That field is the CONSENT SIGNAL:
+  without clearing it, the next start would put an agent back into a channel it deliberately left.
+  The rest of the credential is kept — channel membership is still valid.
+
+**Safety.** Credentials are keyed per working directory, so reading this directory's own file
+cannot inherit another project's session. The agent-session id need not be correct here; auto-relay
+re-resolves it on every wake. We register rather than merely announce: announcing without
+registering would make every leftover bridge immortal — exempt from reap signal 4, yet never
+superseding itself.
+
+### Fixed
+
+- **The presence restore now replays the stored `peerSecret`.** `registerPeer()` takes it as the
+  11th, OPTIONAL parameter and the restore passed ten. A peer owned by an EARLIER token — the normal
+  state after a re-join — answered `PEER_NOT_YOURS`, the restore failed, and the agent stayed
+  offline: precisely the state the feature exists to leave. Per the TypeScript vault
+  (`concepts/Optional_Parameters`), an omitted optional parameter is silently `undefined`, so
+  **deleting the argument left both `tsc --noEmit` and the unit tests at exit 0**. The positional
+  tuple is now extracted as `presenceRegisterArgs()` and every position is pinned by test.
+
 ## 3.23.9 — 2026-09-06
 
 ### Fixed — `cogent_health_check` described the RELAY, not this bridge

package/README.md

@@ -116,7 +116,9 @@ codex mcp add cogent \
 ### Gemini
 
 Gemini joins a channel as a **standalone poll-agent**, not a plugin — it polls the relay and
-answers on its own. Nothing to install as an MCP server, and nothing to `plugin update`.
+answers on its own. Nothing to install as an MCP server, and nothing to `plugin update`: you
+restart the process to pick up a new version. A systemd unit is provided at
+`scripts/cogent-gemini-agent.service`.
 
 ```bash
 export GEMINI_API_KEY=<your-key>
@@ -124,8 +126,18 @@ COGENT_GEMINI_CHANNEL=<channel> COGENT_GEMINI_SECRET=<secret> COGENT_GEMINI_PEER
   node scripts/cogent-gemini-agent.mjs
 ```
 
-It registers itself and answers directed messages and human broadcasts like any other agent.
-A systemd unit is provided at `scripts/cogent-gemini-agent.service`.
+It registers itself, answers directed messages and human broadcasts, and shows up in
+`/cogent peers` like any other peer. Three differences are worth knowing before you wire it in:
+
+1. **It replies on a poll, not a wake.** Claude Code and Codex are resumed the instant a message
+   arrives. Gemini checks the relay on an interval (`COGENT_GEMINI_POLL_MS`, default 4000 ms), so
+   its answers typically land a few seconds later than a plugin agent's.
+2. **It answers; it does not start conversations.** A poll-agent has no `cogent_send_message`
+   tool, so it cannot post unprompted or open a thread — it only responds to what it is sent.
+3. **An API key is required.** Google no longer supports subscription auth for the Gemini CLI, so
+   `GEMINI_API_KEY` is the only rail. If the key is missing, disabled or out of quota the agent
+   still registers and joins the channel — it then replies with the vendor's error instead of
+   going silent, so check its replies, not just the peer list.
 
 <!-- COGENT:COMMANDS:START -->
 <!-- Generated by scripts/sync-docs.mjs from server/src/install/commands.ts.

package/dist/index.js

@@ -2,7 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
 import { startUpdateCheckLoop } from "./backend/npm-update-check.js";
-import { runStartup, runPreflights, resolvePendingLabel, isCloudMode, setInboxNotifier, cloudWsClient, cloudInbox, autoRelay } from "./startup.js";
+import { runStartup, runPreflights, resolvePendingLabel, isCloudMode, setInboxNotifier, cloudWsClient, cloudInbox, autoRelay, restorePeerPresence } from "./startup.js";
 import { logger } from "./logger.js";
 import { registerRegisterPeerTool } from "./tools/register-peer.js";
 import { registerSendMessageTool } from "./tools/send-message.js";
@@ -145,6 +145,18 @@ async function main() {
     void runPreflights().catch((err) => {
         logger.warn(`Preflight error (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
     });
+    // PRESENCE. Work out whether this agent is actually IN its channel, and if it owns a
+    // peer there but has not registered it, put it back. An agent whose bridge is running
+    // while its peer is absent is invisible to everyone messaging it, and every repair in
+    // this client used to sit behind a successful register — so when registration was the
+    // thing that did not happen, nothing recovered and nothing cleaned up. Measured: 18
+    // live bridges on one checkout, peer absent from a healthy channel for five days.
+    // States and the full explanation: services/peer-presence.ts.
+    // Fire-and-forget for the same reason as the two above: it does network I/O and must
+    // never precede `initialize`. Never throws; guarded anyway.
+    void restorePeerPresence().catch((err) => {
+        logger.warn(`Presence restore error (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+    });
     // Best-effort proactive update nudge. Fire-and-forget: never blocks the server
     // becoming ready, never throws, and writes only to STDERR (stdout is the MCP
     // protocol). Stays silent unless a newer cogent-bridge is published on npm.

package/dist/index.js.map

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

package/dist/services/peer-presence.d.ts

@@ -0,0 +1,77 @@
+/** The four states an agent can be in with respect to its channel. */
+export type PresenceState = "local" | "deferred" | "offline" | "online";
+/** What a presence evaluation concluded, and what it did about it. */
+export type PresenceOutcome = {
+    state: "local" | "deferred" | "online";
+    restored: false;
+    detail: string;
+} | {
+    state: "online";
+    restored: true;
+    peerId: string;
+    detail: string;
+} | {
+    state: "offline";
+    restored: false;
+    detail: string;
+};
+export interface PresenceDeps {
+    /** True only when the ACTIVE backend really is the cloud one — not a configuration flag. */
+    isCloudConfigured: () => boolean;
+    /** True when something already registered in THIS process; its state is authoritative. */
+    alreadyRegisteredInProcess: () => boolean;
+    /**
+     * Is a LIVE bridge already announcing this peer for this working directory?
+     *
+     * 🔴 THE SHARED-CHECKOUT CASE. There is ONE credential file per cwd, so every bridge in a
+     * checkout reads the SAME peerId. Two agents legitimately share a checkout under DIFFERENT
+     * peer identities (marvin-coder + marvin-mobile — which is why the ownership registry is keyed
+     * on (cwd, peerId) and not cwd alone). Without this check, a second bridge restores the first
+     * agent's peerId, supersession stands one of them down, and an agent silently loses its own
+     * identity. Proven by controlled A/B: with the restore unguarded, wake-dedup-matrix-test
+     * --topology two-peer could no longer detect its own break (STAYED_GREEN, 0 overlapping
+     * resumes); with presence off it went RED with 1. The gate was telling the truth.
+     */
+    peerAlreadyServed: (peerId: string) => boolean;
+    loadCredentials: () => Promise<{
+        endpoint?: string;
+        sessionId?: string;
+        token?: string;
+        peerId?: string;
+        /** AUD-003 ownership proof, issued once when this peer was created. */
+        peerSecret?: string;
+    } | null>;
+    /** Go cloud-live and register, restoring the channel entry. Throws on failure. */
+    goOnline: (peer: {
+        peerId: string;
+        endpoint: string;
+        sessionId: string;
+        token: string;
+        cwd: string;
+        label: string;
+        /** Replayed on register so a peer owned by an EARLIER token can be reclaimed. */
+        peerSecret?: string;
+    }) => Promise<void>;
+    cwd: () => string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Automatic presence restore. ON by default — a default-off self-heal heals nobody.
+ * Opt out with COGENT_AUTO_PRESENCE=false to observe the state without acting on it.
+ */
+export declare function autoPresenceEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Determine this agent's presence and, when it is `offline` with a peer it owns,
+ * bring it back `online`.
+ *
+ * NEVER THROWS. Runs fire-and-forget after the MCP transport connects — the
+ * `initialize` handshake must never wait on I/O (scripts/startup-nonblocking-test.mjs).
+ */
+export declare function restorePresence(deps: PresenceDeps): Promise<PresenceOutcome>;
+/** Record the evaluated presence. Called by startup after each evaluation. */
+export declare function setPresence(outcome: PresenceOutcome): void;
+/** The agent's own view of its channel presence. Null until first evaluated. */
+export declare function getPresence(): PresenceOutcome | null;
+/** Report the outcome once, at a level that matches how much it matters. */
+export declare function logPresence(outcome: PresenceOutcome): void;
+//# sourceMappingURL=peer-presence.d.ts.map

package/dist/services/peer-presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-presence.d.ts","sourceRoot":"","sources":["../../src/services/peer-presence.ts"],"names":[],"mappings":"AAuDA,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAExE,sEAAsE;AACtE,MAAM,MAAM,eAAe,GACvB;IAAE,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,4FAA4F;IAC5F,iBAAiB,EAAE,MAAM,OAAO,CAAC;IACjC,0FAA0F;IAC1F,0BAA0B,EAAE,MAAM,OAAO,CAAC;IAC1C;;;;;;;;;;;OAWG;IACH,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAC/C,eAAe,EAAE,MAAM,OAAO,CAAC;QAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,uEAAuE;QACvE,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,IAAI,CAAC,CAAC;IACV,kFAAkF;IAClF,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,iFAAiF;QACjF,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAIjF;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAkFlF;AAYD,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAE1D;AAED,gFAAgF;AAChF,wBAAgB,WAAW,IAAI,eAAe,GAAG,IAAI,CAEpD;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAW1D"}

package/dist/services/peer-presence.js

@@ -0,0 +1,181 @@
+// ---------------------------------------------------------------------------
+// PEER PRESENCE — what state this agent is in on its channel, why, and getting
+// it back to `online` without anyone being told to restart something.
+//
+// ── THE VOCABULARY, taken from what this codebase already says ──────────────
+//   "local"     COGENT_LOCAL / no relay. Presence is not a concept here.
+//   "deferred"  EXISTING TERM (backend-provider.ts): cloud-CONFIGURED but never joined —
+//               there are no stored credentials for this working directory. Nothing to
+//               restore; the agent must join a channel first.
+//   "offline"   Stored credentials name a peer for this working directory, but this
+//               process has not registered it. The bridge is running; the AGENT IS NOT
+//               IN THE CHANNEL. Other peers see it as absent and cannot address it.
+//   "online"    Registered. The channel lists this agent and messages reach it.
+//
+// ── HOW AN AGENT ENDS UP `offline` — the mechanism, stated plainly ──────────
+// Registration is an explicit act: something must call `cogent_register_peer`. The
+// bridge starting does NOT register — it only publishes the tools. So every time an
+// agent session starts, the bridge comes up holding valid credentials while the agent
+// is absent from its own channel, and stays that way until the agent calls the tool.
+// If the agent never calls it — it forgot, it crashed first, the session was resumed
+// from a transcript that had already registered — the peer is never (re-)created, and
+// the relay's stale sweep eventually deletes the entry left over from last time.
+//
+// That state used to be both SILENT and SELF-PERPETUATING, because every repair in
+// this client sat behind a successful registration:
+//   - announceBridge()       (auto-relay) — written at register time
+//   - reapStaleBridges()     (auto-relay) — "only after a peer is genuinely registered"
+//   - triggerReRegistration()(startup)    — reads in-memory state, null in a fresh process
+// So when registration was the thing that did not happen, nothing recovered and nothing
+// cleaned up. Measured 2026-09-14 on one checkout: 18 live bridges at 3.23.9, last
+// successful register five days earlier, the peer absent from a healthy Team channel
+// whose two other agents were present and waiting on it.
+//
+// ── WHY RESTORING IT IS SAFE ────────────────────────────────────────────────
+//  - Credentials are keyed PER WORKING DIRECTORY
+//    (~/.cogent/credentials/<sha256(cwd)[..16]>.json, commit f758d8ee). Reading this
+//    directory's own file cannot inherit another project's session — that was the
+//    LEGACY GLOBAL file, which is only ever `fs.access`'d for a warning and never read.
+//  - The agent-session id need not be correct here: auto-relay re-resolves it on every
+//    wake (auto-relay.ts, "Only adopt a resolved id") and register-peer itself falls
+//    back to the channel session id on an unresolved resolution.
+//  - `peerId` in the credential is the CONSENT SIGNAL. create/join write credentials
+//    without one, and deregister clears it, so a deliberate departure is never undone.
+//
+// ── WHY WE DO NOT JUST ANNOUNCE ─────────────────────────────────────────────
+// Reap signal 4 skips any ANNOUNCED pid, reasoning that an announced bridge is 3.23.4+
+// and stands down by itself. Announcing WITHOUT registering would make every leftover
+// immortal: exempt from reaping, yet never superseding itself (supersession is only
+// consulted on a wake, which a bridge with no peer never gets). The invariant is "a live
+// bridge either REGISTERS — and so announces and can stand down — or it stays reapable."
+// Restoring presence registers, so the announce it performs is correct.
+// ---------------------------------------------------------------------------
+import { logger } from "../logger.js";
+/**
+ * Automatic presence restore. ON by default — a default-off self-heal heals nobody.
+ * Opt out with COGENT_AUTO_PRESENCE=false to observe the state without acting on it.
+ */
+export function autoPresenceEnabled(env = process.env) {
+    const v = env.COGENT_AUTO_PRESENCE;
+    if (v === undefined || v === "")
+        return true;
+    return !/^(0|false|no|off)$/i.test(v.trim());
+}
+/**
+ * Determine this agent's presence and, when it is `offline` with a peer it owns,
+ * bring it back `online`.
+ *
+ * NEVER THROWS. Runs fire-and-forget after the MCP transport connects — the
+ * `initialize` handshake must never wait on I/O (scripts/startup-nonblocking-test.mjs).
+ */
+export async function restorePresence(deps) {
+    try {
+        if (!deps.isCloudConfigured()) {
+            return { state: "local", restored: false, detail: "local mode — presence does not apply" };
+        }
+        if (deps.alreadyRegisteredInProcess()) {
+            return { state: "online", restored: false, detail: "registered by this process" };
+        }
+        const creds = await deps.loadCredentials();
+        if (!creds || !creds.endpoint || !creds.sessionId || !creds.token) {
+            return {
+                state: "deferred",
+                restored: false,
+                detail: "no stored channel credentials for this working directory — join a channel first",
+            };
+        }
+        if (!creds.peerId) {
+            // Credentials WITHOUT a peerId: created by join/create, or cleared by a deliberate
+            // deregister. Either way this agent is not meant to be in the channel right now.
+            return {
+                state: "deferred",
+                restored: false,
+                detail: "channel credentials exist but name no peer — nothing was registered here",
+            };
+        }
+        const peerId = creds.peerId;
+        // Someone live is already this peer. Registering again would take the identity from them.
+        if (deps.peerAlreadyServed(peerId)) {
+            return {
+                state: "online",
+                restored: false,
+                detail: `peer '${peerId}' is already served by a live bridge for this working directory`,
+            };
+        }
+        if (!autoPresenceEnabled(deps.env ?? process.env)) {
+            // Report the state, take no action. This is the "observe, do not act" mode.
+            return {
+                state: "offline",
+                restored: false,
+                detail: `peer '${peerId}' is not registered and COGENT_AUTO_PRESENCE is off — this agent is absent from its channel`,
+            };
+        }
+        await deps.goOnline({
+            peerId,
+            endpoint: creds.endpoint,
+            sessionId: creds.sessionId,
+            token: creds.token,
+            cwd: deps.cwd(),
+            // 🔴 THE PEER'S DISPLAY LABEL IS NOT PERSISTED ANYWHERE — only the CHANNEL's is,
+            // in credentials.label (create-session.ts writes `label: data.label`; join-session
+            // writes the resolved channel label). Using that would label the agent after the
+            // channel: a restore once put "paymentorchestrator" beside a sibling called "POFE".
+            // peerId is the one identifier we hold that genuinely names this agent. The
+            // operator's chosen label returns on the next cogent_register_peer, which carries it.
+            label: peerId,
+            // 🔴 WITHOUT THIS THE RESTORE CANNOT RECLAIM ITS OWN PEER. A re-join issues a NEW
+            // token, and AUD-003 ownership is proven by the token that CREATED the peer or by
+            // the secret issued with it. Omitting it means an entry owned by an earlier token
+            // answers PEER_NOT_YOURS and the agent stays offline — precisely the state this
+            // module exists to leave. The secret is in the credential file; send it.
+            peerSecret: creds.peerSecret,
+        });
+        return {
+            state: "online",
+            restored: true,
+            peerId,
+            // Says what THIS process did. Whether the relay now lists the peer is the relay's
+            // state, and asserting it from here would be a success nobody measured.
+            detail: `re-registered peer '${peerId}' from stored credentials`,
+        };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+            state: "offline",
+            restored: false,
+            detail: `presence restore failed: ${reason}`,
+        };
+    }
+}
+/**
+ * Last evaluated presence, so cogent_health_check can report the agent's own state
+ * without re-probing the relay.
+ *
+ * It lives HERE, in the leaf module, and not in startup.ts: a tool importing startup.ts
+ * creates an import cycle (tools -> startup -> tools) and the imported binding reads back
+ * `undefined` at call time. That cost 26 health-check tests once; do not move it.
+ */
+let lastPresence = null;
+/** Record the evaluated presence. Called by startup after each evaluation. */
+export function setPresence(outcome) {
+    lastPresence = outcome;
+}
+/** The agent's own view of its channel presence. Null until first evaluated. */
+export function getPresence() {
+    return lastPresence;
+}
+/** Report the outcome once, at a level that matches how much it matters. */
+export function logPresence(outcome) {
+    if (outcome.state === "online" && outcome.restored) {
+        logger.info(`Presence: offline -> online — ${outcome.detail}. This agent is addressable on its ` +
+            `channel again, and leftover bridges for this checkout are now reapable.`);
+    }
+    else if (outcome.state === "offline") {
+        logger.warn(`Presence: OFFLINE — ${outcome.detail}.`);
+    }
+    else {
+        logger.debug(`Presence: ${outcome.state} — ${outcome.detail}.`);
+    }
+}
+//# sourceMappingURL=peer-presence.js.map

package/dist/services/peer-presence.js.map

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

package/dist/startup.d.ts

@@ -1,5 +1,6 @@
 import { CloudWsClient, MessageInbox } from "./cloud/index.js";
 import { HttpClient } from "./cloud/http-client.js";
+import { type PresenceOutcome } from "./services/peer-presence.js";
 export { autoRelay } from "./services/auto-relay.js";
 export declare let cloudWsClient: CloudWsClient | null;
 export declare let cloudInbox: MessageInbox | null;
@@ -18,6 +19,33 @@ export declare function setInboxNotifier(fn: () => void): void;
  * Debounced: only one re-registration can run at a time.
  */
 export declare function triggerReRegistration(): Promise<void>;
+/**
+ * Evaluate this agent's PRESENCE on its channel and, when it is `offline` with a peer it
+ * owns, bring it back `online`. See services/peer-presence.ts for the state vocabulary,
+ * how an agent ends up offline, and why restoring it is safe.
+ *
+ * Fire-and-forget from index.ts AFTER the transport connects — it performs network I/O
+ * and must never precede the `initialize` handshake (scripts/startup-nonblocking-test.mjs).
+ */
+/**
+ * The exact positional argument tuple for a presence restore's registerPeer call.
+ *
+ * 🔴 EXTRACTED SO IT CAN BE TESTED. registerPeer's trailing parameters are OPTIONAL, and
+ * per the TypeScript vault (concepts/Optional_Parameters -> sources/.../0281) omitting one
+ * "will provide the function with an `undefined` value parameter" — silently. Measured:
+ * deleting `peerSecret` from the call site left BOTH `tsc --noEmit` AND the presence unit
+ * tests at exit 0, because those tests cover the module, not this wiring. A dropped
+ * ownership proof means a peer owned by an earlier token can never be reclaimed, and the
+ * agent stays offline. The type system cannot see it; this tuple + its test can.
+ */
+export declare function presenceRegisterArgs(p: {
+    peerId: string;
+    sessionId: string;
+    cwd: string;
+    label: string;
+    peerSecret?: string;
+}): [string, string, string, string, string, "agent", undefined, undefined, string, string, string | undefined];
+export declare function restorePeerPresence(): Promise<PresenceOutcome>;
 /** Test seam: is a label still waiting to be resolved post-connect? */
 export declare function hasPendingLabelResolve(): boolean;
 /**

package/dist/startup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"startup.d.ts","sourceRoot":"","sources":["../src/startup.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAapD,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAiBrD,eAAO,IAAI,aAAa,EAAE,aAAa,GAAG,IAAW,CAAC;AACtD,eAAO,IAAI,UAAU,EAAE,YAAY,GAAG,IAAW,CAAC;AAClD,eAAO,IAAI,eAAe,EAAE,UAAU,GAAG,IAAW,CAAC;AAKrD;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AASD,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAGrD;AAiHD;;;;GAIG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CA8C3D;AAqFD,uEAAuE;AACvE,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAsCzD;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAwCf;AAMD,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAqMhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAkBnD"}
+{"version":3,"file":"startup.d.ts","sourceRoot":"","sources":["../src/startup.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EAA6C,KAAK,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAa9G,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAiBrD,eAAO,IAAI,aAAa,EAAE,aAAa,GAAG,IAAW,CAAC;AACtD,eAAO,IAAI,UAAU,EAAE,YAAY,GAAG,IAAW,CAAC;AAClD,eAAO,IAAI,eAAe,EAAE,UAAU,GAAG,IAAW,CAAC;AAKrD;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AASD,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAGrD;AAiHD;;;;GAIG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CA8C3D;AAED;;;;;;;GAOG;AACH;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAc9G;AAED,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,eAAe,CAAC,CAsCpE;AAsFD,uEAAuE;AACvE,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAsCzD;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAwCf;AAMD,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAqMhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAkBnD"}

package/dist/startup.js

@@ -14,6 +14,8 @@ import { loadCredentials, hasJoinedInProcess, legacyGlobalCredentialsExist, } fr
 import { CloudWsClient, MessageInbox } from "./cloud/index.js";
 import { HttpClient } from "./cloud/http-client.js";
 import { autoRelay } from "./services/auto-relay.js";
+import { restorePresence, logPresence, setPresence } from "./services/peer-presence.js";
+import { listLiveBridges } from "./services/wake-ownership.js";
 import { heartbeat } from "./services/heartbeat.js";
 import { preflightCodex, preflightCodexSandbox, preflightCodexServerCollision, } from "./services/codex-preflight.js";
 import { setSandboxOverride } from "./services/codex-cli.js";
@@ -184,6 +186,81 @@ export async function triggerReRegistration() {
         reRegistrationInProgress = false;
     }
 }
+/**
+ * Evaluate this agent's PRESENCE on its channel and, when it is `offline` with a peer it
+ * owns, bring it back `online`. See services/peer-presence.ts for the state vocabulary,
+ * how an agent ends up offline, and why restoring it is safe.
+ *
+ * Fire-and-forget from index.ts AFTER the transport connects — it performs network I/O
+ * and must never precede the `initialize` handshake (scripts/startup-nonblocking-test.mjs).
+ */
+/**
+ * The exact positional argument tuple for a presence restore's registerPeer call.
+ *
+ * 🔴 EXTRACTED SO IT CAN BE TESTED. registerPeer's trailing parameters are OPTIONAL, and
+ * per the TypeScript vault (concepts/Optional_Parameters -> sources/.../0281) omitting one
+ * "will provide the function with an `undefined` value parameter" — silently. Measured:
+ * deleting `peerSecret` from the call site left BOTH `tsc --noEmit` AND the presence unit
+ * tests at exit 0, because those tests cover the module, not this wiring. A dropped
+ * ownership proof means a peer owned by an earlier token can never be reclaimed, and the
+ * agent stays offline. The type system cannot see it; this tuple + its test can.
+ */
+export function presenceRegisterArgs(p) {
+    return [
+        p.peerId,
+        p.sessionId,
+        p.cwd,
+        p.label,
+        CLIENT_VERSION,
+        "agent",
+        undefined, // channelSessionId — not tracked on a presence restore
+        undefined, // capabilities — likewise
+        deriveWorkspaceId(p.cwd),
+        p.sessionId, // threadId
+        p.peerSecret, // AUD-003 ownership proof — reclaims a peer owned by an earlier token
+    ];
+}
+export async function restorePeerPresence() {
+    const outcome = await restorePresence({
+        // The endpoint being a relay URL is what makes presence meaningful. We deliberately do
+        // NOT gate on the active backend being the cloud one: at startup it is still the
+        // deferred FileBackend placeholder, and gating on it made this whole path inert
+        // (measured: "skipped: not-cloud-mode" with valid credentials on disk).
+        isCloudConfigured: () => {
+            const ep = getConfig().COGENT_ENDPOINT;
+            return !!ep && isCloudEndpoint(ep);
+        },
+        alreadyRegisteredInProcess: () => autoRelay.getDiagnostics().registered,
+        peerAlreadyServed: (peerId) => {
+            try {
+                return listLiveBridges(process.cwd(), peerId).some((b) => b.pid !== process.pid);
+            }
+            catch {
+                return false; // unreadable registry ⇒ no proof of competition ⇒ proceed
+            }
+        },
+        loadCredentials: () => loadCredentials(),
+        cwd: () => process.cwd(),
+        goOnline: async ({ peerId, endpoint, sessionId, token, cwd, label, peerSecret }) => {
+            // Swap the deferred placeholder for a real cloud backend the supported way — the
+            // same call join-session uses. Building a second backend here instead would leave
+            // the tools on the placeholder and the presence path on another: a split brain.
+            await reinitCloudBackend(endpoint, sessionId, token);
+            const backend = getBackend();
+            await backend.registerPeer(...presenceRegisterArgs({ peerId, sessionId, cwd, label, peerSecret }));
+            // Wiring auto-relay is the POINT, not a side effect: setLocalPeer() is what calls
+            // announceBridge() and reapStaleBridges(), so restoring presence is also what makes
+            // leftover bridges for this checkout reapable again.
+            autoRelay.setLocalPeer(peerId, sessionId, cwd, "agent", label, sessionId);
+            if (cloudWsClient)
+                cloudWsClient.setPeerId(peerId);
+            heartbeat.restart();
+        },
+    });
+    setPresence(outcome);
+    logPresence(outcome);
+    return outcome;
+}
 // ---------------------------------------------------------------------------
 // Helper to create a CloudWsClient with standard callbacks
 // ---------------------------------------------------------------------------