@essentialai/cogent-bridge 3.20.7 → 3.21.1

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## 3.21.1 — 2026-08-31
+
+### Fixed — a label session with an unreachable relay delayed the MCP handshake by ~2.4s
+
+`runStartup()` is awaited BEFORE `server.connect(transport)`, so anything slow in it is dead air
+the MCP client counts against its `initialize` timeout. Resolving a `COGENT_SESSION_ID` **label**
+to a session UUID did `await fetch(...)` there, guarded by a 2500 ms `AbortSignal` and a comment
+claiming the timeout kept the handshake safe. It did not: **bounding a blocking call does not make
+it non-blocking, it only caps the stall.** Measured against a blackhole relay, it added a
+reproducible **+2437 ms** to `initialize` — on top of process boot, on exactly the cold hosts where
+this previously surfaced as "connection closed: initialize response".
+
+The label resolve now runs AFTER connect, like the vendor-CLI preflight already did. Startup enters
+the existing, fully supported deferred mode immediately; on success the post-connect resolve
+upgrades the placeholder backend through `reinitCloudBackend()`, the same path
+`cogent_join_session` uses. Measured after the fix: **+4 ms**.
+
+### Fixed — deferred agents never got the `cogent://inbox` resource
+
+Registration was gated on `cloudInbox` existing *at startup*, which excluded every agent that joins
+via `cogent_join_session` rather than pre-supplying credentials — i.e. the common case. Their inbox
+is created later by `reinitCloudBackend()`, long after registration ran, so `cogent://inbox` was
+never advertised while `sendResourceUpdated()` fired for a resource that did not exist. The resource
+is now gated on cloud MODE and reads the inbox lazily, and the host notifier is bound through
+startup so it follows the inbox across a swap instead of holding a reference to a discarded object.
+
+### Changed — the startup gate now measures blocking instead of machine speed
+
+`scripts/startup-nonblocking-test.mjs` asserted an ABSOLUTE budget (spawn → `initialize` <= 2000 ms).
+That number is dominated by Node boot plus loading a ~1 MB bundle, so on a busy machine it measured
+LOAD: during the 3.21.0 release it went red on a box that was concurrently building and running
+three live matrices, while an interleaved A/B against the previous commit showed no regression at
+all. Worse, its second budget (4000 ms) had been calibrated to *accommodate* the 2.4 s stall above
+rather than catch it — which is why it flickered instead of failing honestly.
+
+It is now a controlled experiment: the same bridge is run with and without the slow knob,
+interleaved, and the MEDIANS are compared. Boot and module load appear in both arms and cancel out,
+so the result is load-independent. The control arm is reported and separately bounded, so the gate
+distinguishes "the product is blocking" from "this machine is too loaded to measure" — previously
+indistinguishable. Mutation-tested in both directions via the new `--bridge` flag.
+
+### Changed — test isolation is now explicit
+
+`vitest.config.ts` pins `pool: "forks"` + `isolate: true`. Several suites resolve agent state through
+`os.homedir()` and therefore mutate `process.env.HOME`; under a threads pool they share one
+`process.env` and clobber each other. Verified: `--pool=threads` fails 3 of those tests, `forks`
+passes all 21. This was a correctness requirement riding on an inherited default.
+
+## 3.21.0 — 2026-08-31
+
+### Fixed — auto-wake refused on machines whose agent state is not in the default place
+
+A developer's Claude Code peer refused every wake with `no candidate sessions found for cwd`,
+from its very first register. Codex→Claude failed while Claude→Codex worked — the asymmetry was
+the clue: **only the Claude Code rail derived the transcript location, and it derived it twice
+over.**
+
+```
+<config root> / projects / <cwd with non-alphanumerics turned into dashes>
+```
+
+Both halves were guesses. The root was `CLAUDE_CONFIG_DIR` **or** a hardcoded `~/.claude` — one
+guess, never verified. The cwd half ran a raw `String.replace` on the path string the agent
+passed to `cogent_register_peer`, so every other spelling of the same directory encoded to a
+directory that does not exist: a trailing slash, a `.` segment, or a symlinked path (macOS
+`/tmp` → `/private/tmp`, `/var` → `/private/var`). Both misses were swallowed by
+`catch { return [] }`, indistinguishable from an empty machine. The Codex rail had already been
+hardened against exactly this (`cwdCanonicals`); the Claude rail never was.
+
+**Session discovery is now layered, and only the last layer guesses:**
+
+1. **Reported (authoritative).** The host hands every hook `cwd`, `session_id` and
+   `transcript_path`. A new `SessionStart` hook (`record-session.mjs`) and the existing Stop hook
+   persist that trio to `~/.cogent/agent-sessions/`. The resolver prefers it, so there is nothing
+   to derive — this works with **any** relocated config dir, with no configuration at all.
+2. **Discovery.** No record yet (e.g. Team agents, which run without the plugin) → roots are
+   enumerated instead of guessed: `CLAUDE_CONFIG_DIR`, then roots **learned** from transcript
+   paths agents reported, then `~/.claude` and `~/.config/claude` — each crossed with the
+   canonical forms of the cwd (`path.resolve` **and** `fs.realpath`).
+3. **Fail loud.** Nothing matched → the refusal now **names every path it scanned**, and a
+   zero-candidate result at register time is a WARN plus a `warning`/`scannedPaths` field in the
+   tool result. Previously registration silently pinned the *cloud* session id, which `--resume`
+   can never open, guaranteeing that every later wake was refused.
+
+One recorded session teaches the machine its root, so other projects under the same root resolve
+with no record of their own.
+
+### Fixed — "clean uninstall" removed nothing for users with a relocated config dir
+
+`scripts/uninstall-cogent.sh` and the hosted `uninstall.sh` hardcoded `$HOME/.claude` and
+`$HOME/.codex`, so a custom-dir user got a success report while every plugin file stayed on
+disk — which then makes a "fresh install test" silently measure the old install. Both scripts now
+enumerate the same roots the bridge does (env → learned → conventions) and clean each one, and
+the new `~/.cogent/agent-sessions` state directory is purged.
+
+### Guarded
+
+- The hook↔bridge record path and `rootFromTranscriptPath` are asserted identical by
+  `scripts/wake-race-test.mjs` (a mismatch would make the authoritative layer silently inert),
+  and `record-session.mjs` joins the byte-identical plugin-parity check.
+- New tests: representation tolerance (trailing slash / `.` segment / symlink / dedupe), the
+  learned-record store, and an end-to-end proof against a config root no heuristic could guess.
+  Verified by mutation — each layer was disabled in turn and the relevant tests went red.
+
 ## 3.20.7 — 2026-08-31
 
 ### Fixed — `cogent-codex` did nothing when installed from npm (silent exit)

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 { checkForUpdate, setLastNudge } from "./backend/npm-update-check.js";
-import { runStartup, runPreflights, cloudWsClient, cloudInbox, autoRelay } from "./startup.js";
+import { runStartup, runPreflights, resolvePendingLabel, isCloudMode, setInboxNotifier, cloudWsClient, cloudInbox, autoRelay } from "./startup.js";
 import { logger } from "./logger.js";
 import { registerRegisterPeerTool } from "./tools/register-peer.js";
 import { registerSendMessageTool } from "./tools/send-message.js";
@@ -78,23 +78,39 @@ async function main() {
     registerSendMailTool(server);
     registerFetchMailTool(server);
     registerRotateMailCredsTool(server);
-    // Register MCP inbox resource if cloud mode is active
-    if (cloudInbox) {
+    // Register the MCP inbox resource for cloud mode.
+    //
+    // 🔴 This used to be gated on `cloudInbox` EXISTING AT STARTUP, which quietly
+    // excluded every deferred agent — i.e. anyone who joins with
+    // cogent_join_session rather than pre-supplying credentials. Their inbox is
+    // created later by reinitCloudBackend(), long after this registration ran, so
+    // `cogent://inbox` was never advertised and the sendResourceUpdated() below
+    // fired for a resource that did not exist. Gate on cloud MODE and read the
+    // inbox LAZILY inside the handler, so deferred and pre-credentialed agents get
+    // the same surface.
+    if (isCloudMode()) {
         server.registerResource("cogent_inbox", "cogent://inbox", {
             description: "Incoming messages received via cloud bridge WebSocket. Read this resource to see new messages from other peers.",
             mimeType: "application/json",
-        }, async (uri) => ({
+        }, 
+        // Read the inbox LAZILY: in deferred mode it does not exist yet and is
+        // created later by reinitCloudBackend(). An empty inbox is the honest
+        // answer for "connected to cloud, no session joined yet".
+        async (uri) => ({
             contents: [{
                     uri: uri.href,
                     mimeType: "application/json",
                     text: JSON.stringify({
-                        messages: cloudInbox.getUnread(),
-                        lastMessageId: cloudInbox.getLastMessageId(),
+                        messages: cloudInbox ? cloudInbox.getUnread() : [],
+                        lastMessageId: cloudInbox ? cloudInbox.getLastMessageId() : null,
                     }),
                 }],
         }));
-        // When WS messages arrive, notify the MCP host (Claude Code) that new messages are available
-        cloudInbox.onNewMessage(() => {
+        // When WS messages arrive, notify the MCP host that new messages are available.
+        // Registered through startup so it also binds to an inbox created LATER
+        // (deferred join) — attaching directly here would only ever see the
+        // startup-time inbox, i.e. never in deferred mode.
+        setInboxNotifier(() => {
             try {
                 server.server.sendResourceUpdated({ uri: "cogent://inbox" });
             }
@@ -109,6 +125,16 @@ async function main() {
     await server.connect(transport);
     // Startup banner: always prints regardless of log level
     process.stderr.write(`${SERVER_NAME} v${SERVER_VERSION} running on stdio\n`);
+    // A COGENT_SESSION_ID *label* needs a relay round-trip to become a session UUID.
+    // It runs HERE, after connect, for exactly the same reason preflight does:
+    // awaiting it beforehand added a reproducible +2437 ms to `initialize` against an
+    // unreachable relay (measured by scripts/startup-nonblocking-test.mjs). Bounding
+    // that fetch with a 2500 ms AbortSignal — what the code used to do — caps the
+    // stall but does not remove it. Fire-and-forget; on success it upgrades the
+    // deferred backend via reinitCloudBackend().
+    void resolvePendingLabel().catch((err) => {
+        logger.warn(`Label resolve error (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+    });
     // Platform CLI + sandbox preflight runs AFTER the transport connects: it SPAWNS
     // the vendor CLI (`codex/claude --help`, capped at 10s) and must never precede
     // the `initialize` handshake — a slow spawn there closed the MCP connection on

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC/F,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,8EAA8E;AAC9E,iEAAiE;AACjE,8EAA8E;AAE9E,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,EAAE;IACtC,8DAA8D;IAC9D,IAAK,GAA6B,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QACpD,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChB,OAAO;IACT,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,uBAAuB,GAAG,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IACzE,mDAAmD;AACrD,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE;IAC1C,MAAM,GAAG,GAAG,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtE,MAAM,CAAC,KAAK,CAAC,wBAAwB,GAAG,EAAE,CAAC,CAAC;AAC9C,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,6BAA6B;AAC7B,8EAA8E;AAE9E,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;IACzB,MAAM,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;IAC/C,SAAS,CAAC,IAAI,EAAE,CAAC;IACjB,SAAS,CAAC,IAAI,EAAE,CAAC;IACjB,IAAI,aAAa,EAAE,CAAC;QAClB,aAAa,CAAC,UAAU,EAAE,CAAC;IAC7B,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,CAAC;IACf,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;IACxB,MAAM,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IAC9C,SAAS,CAAC,IAAI,EAAE,CAAC;IACjB,SAAS,CAAC,IAAI,EAAE,CAAC;IACjB,IAAI,aAAa,EAAE,CAAC;QAClB,aAAa,CAAC,UAAU,EAAE,CAAC;IAC7B,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,CAAC;IACf,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,KAAK,UAAU,IAAI;IACjB,oDAAoD;IACpD,sEAAsE;IACtE,MAAM,UAAU,EAAE,CAAC;IAEnB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;IAE7E,oEAAoE;IACpE,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,0BAA0B,CAAC,MAAM,CAAC,CAAC;IACnC,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClC,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,2BAA2B,CAAC,MAAM,CAAC,CAAC;IAEpC,sDAAsD;IACtD,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,CAAC,gBAAgB,CACrB,cAAc,EACd,gBAAgB,EAChB;YACE,WAAW,EAAE,iHAAiH;YAC9H,QAAQ,EAAE,kBAAkB;SAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;YACd,QAAQ,EAAE,CAAC;oBACT,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACnB,QAAQ,EAAE,UAAW,CAAC,SAAS,EAAE;wBACjC,aAAa,EAAE,UAAW,CAAC,gBAAgB,EAAE;qBAC9C,CAAC;iBACH,CAAC;SACH,CAAC,CACH,CAAC;QAEF,6FAA6F;QAC7F,UAAU,CAAC,YAAY,CAAC,GAAG,EAAE;YAC3B,IAAI,CAAC;gBACH,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAAE,GAAG,EAAE,gBAAgB,EAAE,CAAC,CAAC;YAC/D,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,iEAAiE;gBACjE,MAAM,CAAC,IAAI,CAAC,gDAAgD,GAAG,EAAE,CAAC,CAAC;YACrE,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,0BAA0B;IAC1B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,wDAAwD;IACxD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,WAAW,KAAK,cAAc,qBAAqB,CACvD,CAAC;IAEF,gFAAgF;IAChF,+EAA+E;IAC/E,+EAA+E;IAC/E,4EAA4E;IAC5E,oFAAoF;IACpF,KAAK,aAAa,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC1C,MAAM,CAAC,IAAI,CACT,gCAAgC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACnF,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,+EAA+E;IAC/E,6EAA6E;IAC7E,4EAA4E;IAC5E,KAAK,cAAc,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;QACjD,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,IAAI,CACT,gMAAgM,CACjM,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,MAAM,CAAC,KAAK,CAAC,wBAAwB,GAAG,EAAE,CAAC,CAAC;IAC5C,2CAA2C;IAC3C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,KAAK,EAAE,CAAC;IACf,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/services/agent-sessions.d.ts

@@ -0,0 +1,90 @@
+/**
+ * LEARNED AGENT SESSION RECORDS — "the agent told us where it lives".
+ *
+ * 🔴 WHY THIS EXISTS. Everything downstream of the wake rails used to DERIVE the
+ * location of an agent's session transcript:
+ *
+ *     <config root> / projects / <cwd with non-alphanumerics turned into dashes>
+ *
+ * Both halves of that are guesses. The config root was `CLAUDE_CONFIG_DIR` or a
+ * hardcoded `~/.claude` — one guess, never verified. The cwd half assumed the
+ * caller passed the exact canonical spelling of the directory. Either guess being
+ * wrong produced the same dead end: zero candidates, wake refused, and a log line
+ * that never named the path it looked in.
+ *
+ * The agents already publish the truth. Claude Code hands every hook a payload
+ * containing `cwd`, `session_id` and `transcript_path` — an ABSOLUTE path to the
+ * live transcript, with no encoding to reverse and no root to guess. This module
+ * is where that fact is persisted so the resolver can prefer it over inference.
+ *
+ * Layering (see docs + session-resolver):
+ *   1. this record          — authoritative, works with ANY relocated config dir
+ *   2. root discovery       — inference, for agents running without our plugin
+ *   3. fail loud            — name every path probed
+ *
+ * Storage mirrors the existing per-cwd convention exactly (credential-store.ts,
+ * wake-inflight.ts): `~/.cogent/<kind>/<sha256(path.resolve(cwd))[..16]>.json`,
+ * homedir-based on purpose so the bridge and the hook — two processes with
+ * different environments — always agree on the path.
+ */
+/** Platforms that keep a per-cwd session transcript we can learn. */
+export type AgentPlatform = "cc" | "codex";
+export interface AgentSessionRecord {
+    /** The cwd as the agent reported it (already resolved when written). */
+    cwd: string;
+    /** The agent's own session id — what `--resume` / `resume` takes. */
+    sessionId: string;
+    /** Absolute path to the transcript. The whole point: no derivation. */
+    transcriptPath: string;
+    /** Config root implied by transcriptPath, when it could be recovered. */
+    root?: string;
+    platform: AgentPlatform;
+    /** ISO timestamp of the last write. */
+    updatedAt: string;
+}
+/** MUST equal credential-store's hash and check-on-stop.lib.mjs credHashForCwd. */
+export declare function hashCwd(cwd: string): string;
+/** `~/.cogent/agent-sessions/` — the learned-record directory. */
+export declare function agentSessionsDir(): string;
+/**
+ * `~/.cogent/agent-sessions/<hash(cwd)>.<platform>.json`.
+ *
+ * Keyed by platform as well as cwd because one directory can host both a Claude
+ * Code and a Codex agent (that is the normal two-agent Cogent setup) and their
+ * transcripts live in completely different stores.
+ */
+export declare function agentSessionPath(cwd: string, platform: AgentPlatform): string;
+/**
+ * Recover the config ROOT from an absolute transcript path.
+ *
+ * Claude Code lays transcripts out as `<root>/projects/<encoded-cwd>/<id>.jsonl`,
+ * so the root is whatever sits above the `projects` segment — recovered by
+ * structure, never by matching a known prefix, which is what lets a completely
+ * unknown custom location teach us its root.
+ *
+ * Returns null when the shape does not match (a Codex rollout, a temp file, an
+ * agent that changes its layout) — callers must treat the root as optional.
+ */
+export declare function rootFromTranscriptPath(transcriptPath: string): string | null;
+/** Read the learned record for a cwd, or null. Never throws. */
+export declare function readAgentSession(cwd: string, platform: AgentPlatform): Promise<AgentSessionRecord | null>;
+/**
+ * Persist a learned record. Atomic (temp + rename) so a hook and the bridge
+ * writing concurrently can never leave a half-written file for the other to
+ * read — the same discipline peer-registry uses for shared state.
+ * Never throws: learning is an optimisation, never a reason to fail a wake.
+ */
+export declare function writeAgentSession(rec: Omit<AgentSessionRecord, "updatedAt" | "root"> & {
+    root?: string;
+}): Promise<boolean>;
+/**
+ * Every distinct config root this machine has ever taught us, newest first.
+ *
+ * This is what turns one lucky resolution into permanent knowledge: a user with
+ * `CLAUDE_CONFIG_DIR=/data/claude` teaches us that root once, and afterwards
+ * EVERY project on the machine resolves against it — including ones opened in a
+ * shell where the variable was never exported. Bounded work: one readdir plus a
+ * small number of tiny JSON reads.
+ */
+export declare function learnedRoots(platform: AgentPlatform): Promise<string[]>;
+//# sourceMappingURL=agent-sessions.d.ts.map

package/dist/services/agent-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-sessions.d.ts","sourceRoot":"","sources":["../../src/services/agent-sessions.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,aAAa,CAAC;IACxB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mFAAmF;AACnF,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM3C;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,aAAa,GACtB,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ5E;AAED,gEAAgE;AAChE,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAUpC;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,GAAG,MAAM,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACtE,OAAO,CAAC,OAAO,CAAC,CAiBlB;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA4B7E"}

package/dist/services/agent-sessions.js

@@ -0,0 +1,120 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+/** MUST equal credential-store's hash and check-on-stop.lib.mjs credHashForCwd. */
+export function hashCwd(cwd) {
+    return crypto
+        .createHash("sha256")
+        .update(path.resolve(cwd))
+        .digest("hex")
+        .slice(0, 16);
+}
+/** `~/.cogent/agent-sessions/` — the learned-record directory. */
+export function agentSessionsDir() {
+    return path.join(os.homedir(), ".cogent", "agent-sessions");
+}
+/**
+ * `~/.cogent/agent-sessions/<hash(cwd)>.<platform>.json`.
+ *
+ * Keyed by platform as well as cwd because one directory can host both a Claude
+ * Code and a Codex agent (that is the normal two-agent Cogent setup) and their
+ * transcripts live in completely different stores.
+ */
+export function agentSessionPath(cwd, platform) {
+    return path.join(agentSessionsDir(), `${hashCwd(cwd)}.${platform}.json`);
+}
+/**
+ * Recover the config ROOT from an absolute transcript path.
+ *
+ * Claude Code lays transcripts out as `<root>/projects/<encoded-cwd>/<id>.jsonl`,
+ * so the root is whatever sits above the `projects` segment — recovered by
+ * structure, never by matching a known prefix, which is what lets a completely
+ * unknown custom location teach us its root.
+ *
+ * Returns null when the shape does not match (a Codex rollout, a temp file, an
+ * agent that changes its layout) — callers must treat the root as optional.
+ */
+export function rootFromTranscriptPath(transcriptPath) {
+    if (!transcriptPath)
+        return null;
+    const parts = path.resolve(transcriptPath).split(path.sep);
+    // …/<root>/projects/<encoded>/<id>.jsonl → need "projects" with a parent.
+    const i = parts.lastIndexOf("projects");
+    if (i <= 0)
+        return null;
+    const root = parts.slice(0, i).join(path.sep);
+    return root || path.sep;
+}
+/** Read the learned record for a cwd, or null. Never throws. */
+export async function readAgentSession(cwd, platform) {
+    try {
+        const raw = await fs.readFile(agentSessionPath(cwd, platform), "utf-8");
+        const rec = JSON.parse(raw);
+        // A record without the two fields that make it useful is not a record.
+        if (!rec?.sessionId || !rec?.transcriptPath)
+            return null;
+        return rec;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist a learned record. Atomic (temp + rename) so a hook and the bridge
+ * writing concurrently can never leave a half-written file for the other to
+ * read — the same discipline peer-registry uses for shared state.
+ * Never throws: learning is an optimisation, never a reason to fail a wake.
+ */
+export async function writeAgentSession(rec) {
+    try {
+        const full = {
+            ...rec,
+            cwd: path.resolve(rec.cwd),
+            root: rec.root ?? rootFromTranscriptPath(rec.transcriptPath) ?? undefined,
+            updatedAt: new Date().toISOString(),
+        };
+        const target = agentSessionPath(full.cwd, full.platform);
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        const tmp = `${target}.${process.pid}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(full, null, 2), "utf-8");
+        await fs.rename(tmp, target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every distinct config root this machine has ever taught us, newest first.
+ *
+ * This is what turns one lucky resolution into permanent knowledge: a user with
+ * `CLAUDE_CONFIG_DIR=/data/claude` teaches us that root once, and afterwards
+ * EVERY project on the machine resolves against it — including ones opened in a
+ * shell where the variable was never exported. Bounded work: one readdir plus a
+ * small number of tiny JSON reads.
+ */
+export async function learnedRoots(platform) {
+    try {
+        const dir = agentSessionsDir();
+        const files = (await fs.readdir(dir)).filter((f) => f.endsWith(`.${platform}.json`));
+        const recs = await Promise.all(files.map(async (f) => {
+            try {
+                return JSON.parse(await fs.readFile(path.join(dir, f), "utf-8"));
+            }
+            catch {
+                return null;
+            }
+        }));
+        return [
+            ...new Set(recs
+                .filter((r) => Boolean(r?.root))
+                .sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1))
+                .map((r) => r.root)),
+        ];
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=agent-sessions.js.map

package/dist/services/agent-sessions.js.map

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

package/dist/services/cc-cli.d.ts

@@ -1,11 +1,79 @@
 import { CliExecResult } from "../types.js";
+/**
+ * Every transcript directory that could hold this cwd's sessions.
+ *
+ * 🔴 WHY THIS IS NOT ONE PATH. Claude Code names a project dir by replacing each
+ * non-alphanumeric char of the cwd with "-", so EVERY representation of the same
+ * directory encodes to a DIFFERENT name: a trailing slash, a "." segment, or a
+ * symlinked path (macOS `/tmp` -> `/private/tmp`, `/var` -> `/private/var`) each
+ * produce a dir that does not exist. The cwd here is a string the AGENT supplied
+ * to cogent_register_peer — it is not guaranteed to be the canonical form.
+ *
+ * That mismatch is how a fresh dev machine got ZERO candidates from its very
+ * first register (2026-08-31) and refused every wake thereafter. The Codex rail
+ * had already canonicalised for this reason (codex-cli.ts `cwdCanonicals`); this
+ * is the Claude Code rail reaching parity.
+ *
+ * Exported so callers can LOG what was probed — a miss used to be indistinguishable
+ * from an empty dir, which is what made the failure undiagnosable from the logs.
+ */
+export declare function projectDirsFor(cwd: string): Promise<string[]>;
+/**
+ * Every config root that could hold this machine's Claude Code transcripts,
+ * best-first.
+ *
+ * 🔴 WHY THIS IS A LIST. `claudeConfigDir()` returns ONE guess — the env var if
+ * this process happens to see it, otherwise `~/.claude`. A single guess has no
+ * way to be wrong loudly: it just scans a directory that does not exist and
+ * reports "no sessions". Users relocate their agent state (small system disks,
+ * synced or encrypted home dirs, multi-account machines, containers), and the
+ * env var does not always reach the process that needs it.
+ *
+ * Order is deliberate:
+ *   1. `CLAUDE_CONFIG_DIR` — an explicit instruction always wins.
+ *   2. LEARNED roots — recovered from transcript paths the agent itself reported
+ *      (agent-sessions.ts). These are the only entries PROVEN to have held a real
+ *      transcript, which is why they outrank the conventional defaults.
+ *   3. `~/.claude`, then `~/.config/claude` — the conventional locations.
+ *
+ * Probing a few extra directories costs one failed `readdir` each; missing the
+ * user's actual directory costs them the entire auto-wake feature.
+ */
+export declare function claudeConfigRoots(): Promise<string[]>;
+/**
+ * The transcript this cwd's agent REPORTED for itself, if the record is still
+ * valid on disk. This is layer 1 — the authoritative path — and it bypasses both
+ * the root guess and the cwd-encoding guess entirely.
+ *
+ * Returns null when nothing was ever recorded (an agent running without our
+ * plugin) or when the recorded transcript has since been removed, in which case
+ * the caller falls back to discovery.
+ */
+export declare function recordedCandidate(cwd: string): Promise<{
+    sessionId: string;
+    mtimeMs: number;
+} | null>;
+/**
+ * One-line description of the transcript BASE dir and how many project dirs it
+ * holds. Used only when a resolve finds zero candidates, because it separates the
+ * two causes that look identical in the logs:
+ *   • base absent / 0 project dirs → the bridge is looking at the WRONG config dir
+ *     entirely (Claude Code's environment lives elsewhere and CLAUDE_CONFIG_DIR did
+ *     not reach this process).
+ *   • base holds N project dirs but none match → the CWD is the wrong one (or a
+ *     representation this build cannot map — see {@link projectDirsFor}).
+ * Never throws.
+ */
+export declare function transcriptBaseSummary(): Promise<string>;
 /**
  * List all Claude Code session candidates for a cwd as {sessionId, mtimeMs}.
- * Scans <claudeConfigDir()>/projects/<escapedCwd>/*.jsonl — honoring
- * CLAUDE_CONFIG_DIR (default ~/.claude). Returns [] on any error or an
- * empty/absent dir (the resolver treats [] as "no candidates"). Never throws —
- * Vault: Returning-null/Option error pattern (typescript-master-vault
- * concepts/Error_Handling). Stats run in parallel (Vault: Parallelism).
+ * Scans every {@link projectDirsFor} dir for *.jsonl — honoring CLAUDE_CONFIG_DIR
+ * (default ~/.claude). Returns [] on any error or an empty/absent dir (the
+ * resolver treats [] as "no candidates"). Never throws — Vault: Returning-null/
+ * Option error pattern (typescript-master-vault concepts/Error_Handling). Dirs
+ * and stats are probed in parallel (Vault: Parallelism); results are deduped by
+ * sessionId so two cwd forms resolving to one dir cannot inflate the count (a
+ * false ">1" would make the resolver call it "ambiguous" and refuse).
  */
 export declare function listCandidates(cwd: string): Promise<{
     sessionId: string;
@@ -20,6 +88,11 @@ export declare function detectCurrentSession(cwd: string): Promise<string | null
 /**
  * Check whether a Claude Code session file exists on disk.
  * Returns false if the file is missing (session ended or ID is wrong).
+ *
+ * Probes every {@link projectDirsFor} form — a pin validated under the canonical
+ * cwd must still validate when the agent registered a symlinked/trailing-slash
+ * representation of the same directory, or the resolver silently drops the pin
+ * and falls back to guessing by mtime.
  */
 export declare function validateSession(sessionId: string, cwd: string): Promise<boolean>;
 export declare function execClaude(sessionId: string, message: string, cwd: string, timeoutMs?: number): Promise<CliExecResult>;

package/dist/services/cc-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cc-cli.d.ts","sourceRoot":"","sources":["../../src/services/cc-cli.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAK5C;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,CAenD;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKxB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,OAAO,CAAC,CAelB;AAED,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAiLxB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,GACV;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAYpD"}
+{"version":3,"file":"cc-cli.d.ts","sourceRoot":"","sources":["../../src/services/cc-cli.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAM5C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWnE;AAcD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAQ3D;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CASxD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAa7D;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,CAiCnD;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,OAAO,CAAC,CAkBlB;AAED,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAiLxB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,GACV;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAYpD"}