@essentialai/cogent-bridge 3.20.6 → 3.21.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 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)
+
+Running `cogent-codex` printed nothing and returned straight to the prompt. npm installs the
+command as a **symlink**, so `process.argv[1]` is the link while `import.meta.url` is the real
+file; the CLI guard compared them directly, which is always false through a symlink, so
+`main()` never ran. **The entire codex real-time-wake feature was dark for every npm-installed
+user** since the launcher shipped.
+
+Running the built file directly — the only way it had ever been tested — worked fine, which is
+exactly why this reached users. The guard now compares **realpaths**, and a new regression test
+invokes the command *through a symlink*, the way npm installs it (mutation-proven: reverting the
+fix turns it red).
+
+
 ## 3.20.6 — 2026-08-28
 
 ### Fixed — the check-on-stop hook no longer fires inside the auto-relay's capture window (COG-20 root cause)

package/README.md

@@ -69,6 +69,16 @@ turn. **One command installs everything** — the plugin **and** the `cogent-cod
 curl -fsSL https://cogent.tools/install.sh | sh
 ```
 
+**Then reload your shell** so `cogent-codex` is on your PATH — the installer runs in a subshell
+and cannot do this for you:
+
+```bash
+exec $SHELL -l
+```
+
+> Skip this and `cogent-codex` reports `command not found` in the terminal you installed from.
+> Opening a brand-new terminal works too.
+
 Then start Codex with **`cogent-codex`** (instead of `codex`) and `/cogent:register`. `cogent-codex`
 runs Codex under a shared app-server daemon so a peer's message reaches you **mid-session** — the
 bridge auto-detects the rail, **no env var or config needed** (since 3.20.2).
@@ -103,6 +113,85 @@ codex mcp add cogent \
 
 …or, on Codex CLI 0.133.0+, the plugin: `codex plugin marketplace add eaisdevelopment/cogent && codex plugin add cogent@cogent`. Then use `cogent_register_peer` (or `/cogent:register`).
 
+### 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`.
+
+```bash
+export GEMINI_API_KEY=<your-key>
+COGENT_GEMINI_CHANNEL=<channel> COGENT_GEMINI_SECRET=<secret> COGENT_GEMINI_PEER=<name> \
+  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`.
+
+<!-- COGENT:COMMANDS:START -->
+<!-- Generated by scripts/sync-docs.mjs from server/src/install/commands.ts.
+     Do NOT edit inside these markers — run `node scripts/sync-docs.mjs`. -->
+
+## Install
+
+### Claude Code
+
+```bash
+claude plugin marketplace add https://cogent.tools/marketplace.json
+claude plugin install cogent@cogent
+```
+
+### OpenAI Codex
+
+```bash
+curl -fsSL https://cogent.tools/install.sh | sh
+```
+
+**Then reload your shell so cogent-codex is on your PATH — without it the command reports 'command not found' in the terminal you installed from:**
+
+```bash
+exec $SHELL -l
+```
+
+### Gemini
+
+```bash
+export GEMINI_API_KEY=<your-key>
+COGENT_GEMINI_CHANNEL=<channel> COGENT_GEMINI_SECRET=<secret> COGENT_GEMINI_PEER=<name> node scripts/cogent-gemini-agent.mjs
+```
+
+_Standalone poll-agent — no plugin to install or update._
+
+## Updating
+
+**Update from the CLI, then restart.** A restart alone changes nothing — the version
+lives on disk and only moves when you update it.
+
+| Agent | Update | Then |
+|---|---|---|
+| **Claude Code** | `claude plugin update cogent@cogent` | exit and restart the session |
+| **OpenAI Codex** | `codex plugin marketplace upgrade` then `codex plugin add cogent@cogent` | restart cogent-codex |
+| **Gemini** | _(no plugin)_ | restart the agent process (it is a standalone poll-agent, not a plugin) |
+
+Verify it landed:
+
+```bash
+claude plugin list | grep -A2 cogent
+```
+
+## Uninstalling
+
+One command removes Cogent completely — both plugins, the launcher, caches and all
+Cogent state — so you can verify a clean install. macOS, Linux, WSL and Git Bash:
+
+```bash
+curl -fsSL https://cogent.tools/uninstall.sh | sh
+```
+
+> **Never run `rm -rf ~/.cogent` — it also holds credentials Cogent never created and cannot recreate.** Your `.env` files and backups there are always preserved —
+> the script lists everything it kept.
+
+<!-- COGENT:COMMANDS:END -->
+
 ## Local vs Cloud mode
 
 Cogent runs in one of two modes. **Cloud is the default — you don't have to configure anything.**

package/dist/bin/cogent-codex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cogent-codex.d.ts","sourceRoot":"","sources":["../../src/bin/cogent-codex.ts"],"names":[],"mappings":";AAqEA,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAE3D;AAoDD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAO9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1F"}
+{"version":3,"file":"cogent-codex.d.ts","sourceRoot":"","sources":["../../src/bin/cogent-codex.ts"],"names":[],"mappings":";AAsEA,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAE3D;AAoDD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAO9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1F"}

package/dist/bin/cogent-codex.js

@@ -30,6 +30,7 @@
  * macOS + Linux. Windows (loopback `ws://…`) is not yet wired here.
  */
 import { spawn, spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
 import { pathToFileURL } from "node:url";
@@ -221,8 +222,28 @@ async function main() {
         handOff(codexBin, passthrough);
     }
 }
-// Run only when invoked as a CLI — importing this module (tests) must NOT launch codex.
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+/**
+ * Is this module being run as a CLI (rather than imported by a test)?
+ *
+ * 🔴 MUST compare REALPATHS. npm installs `cogent-codex` as a SYMLINK in its bin dir, so when a
+ * user runs it `process.argv[1]` is the link (…/bin/cogent-codex) while `import.meta.url` is the
+ * real file (…/dist/bin/cogent-codex.js). Comparing them directly is always false through a
+ * symlink, so `main()` never ran: the command printed nothing, exited 0, and returned the user
+ * straight to a fresh prompt — the entire codex real-time-wake feature was dark for every
+ * npm-installed user while running the file directly (how it was always tested) worked fine.
+ */
+function invokedAsCli() {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(argv1)).href;
+    }
+    catch {
+        return import.meta.url === pathToFileURL(argv1).href; // unreadable path → best effort
+    }
+}
+if (invokedAsCli()) {
     main().catch((err) => {
         log(`fatal: ${err?.message ?? err}`);
         process.exit(1);

package/dist/bin/cogent-codex.js.map

@@ -1 +1 @@
-{"version":3,"file":"cogent-codex.js","sourceRoot":"","sources":["../../src/bin/cogent-codex.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cogent-codex.js","sourceRoot":"","sources":["../../src/bin/cogent-codex.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACjF,OAAO,EACL,gCAAgC,EAChC,eAAe,GAChB,MAAM,gCAAgC,CAAC;AAExC,SAAS,GAAG,CAAC,GAAW;IACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,qBAAqB;IAClC,MAAM,OAAO,GAAG,eAAe,EAAE,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7C,IAAI,CAAC,gCAAgC,CAAC,IAAI,CAAC;YAAE,OAAO;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,0CAA0C;IACpD,CAAC;IACD,GAAG,CAAC,gEAAgE,CAAC,CAAC;IACtE,GAAG,CAAC,iEAAiE,CAAC,CAAC;IACvE,GAAG,CAAC,OAAO,OAAO,EAAE,CAAC,CAAC;IACtB,GAAG,CAAC,qEAAqE,CAAC,CAAC;IAC3E,GAAG,CAAC,2EAA2E,CAAC,CAAC;IACjF,GAAG,CAAC,4EAA4E,CAAC,CAAC;IAClF,GAAG,CAAC,gEAAgE,CAAC,CAAC;AACxE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAChD,OAAO,wBAAwB,CAAC,IAAI,CAAE,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,UAAU,CAAC,QAAgB;IACxC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACvC,MAAM,EAAE,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7E,IAAI,CAAC;QACH,MAAM,MAAM,GAAW,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;QACtF,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACtC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,CAAC;IAC9C,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,SAAS,mBAAmB;IAC1B,GAAG,CAAC,0EAA0E,CAAC,CAAC;IAChF,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,sDAAsD,CAAC,EAAE;QAC1F,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;IACH,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,GAAG,CAAC,0BAA0B,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,GAAG,CAAC,gDAAgD,GAAG,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC;IAC3E,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC;IAClC,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY;IACrF,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG;IACpF,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE,QAAQ;CACxE,CAAC,CAAC;AAEH,oFAAoF;AACpF,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC;AAE1E;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,WAAqB;IACnD,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,IAAI;YAAE,MAAM;QACtB,IAAI,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC9C,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,WAAqB,EAAE,GAAW;IAC9E,2EAA2E;IAC3E,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7G,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IAChH,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC9C,sFAAsF;IACtF,wDAAwD;IACxD,OAAO,CAAC,UAAU,EAAE,UAAU,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,GAAG,WAAW,CAAC,CAAC;AACpE,CAAC;AAED,sFAAsF;AACtF,SAAS,OAAO,CAAC,QAAgB,EAAE,IAAc;IAC/C,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC1D,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;QAChC,IAAI,MAAM;YAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;;YACzC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;QACxB,GAAG,CAAC,qBAAqB,QAAQ,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACtD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,iBAAiB;IAC9B,IAAI,CAAC;QACH,OAAO,MAAM,YAAY,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,qBAAqB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAM,EAAE,GAAG,MAAM,UAAU,CACzB,2GAA2G,CAC5G,CAAC;YACF,IAAI,EAAE,IAAI,mBAAmB,EAAE,EAAE,CAAC;gBAChC,gBAAgB,EAAE,CAAC;gBACnB,IAAI,CAAC;oBACH,OAAO,MAAM,YAAY,EAAE,CAAC;gBAC9B,CAAC;gBAAC,OAAO,QAAQ,EAAE,CAAC;oBAClB,GAAG,CAAC,2CAA4C,QAAkB,EAAE,OAAO,IAAI,QAAQ,IAAI,CAAC,CAAC;oBAC7F,OAAO,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;YACD,GAAG,CAAC,6EAA6E,CAAC,CAAC;YACnF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,GAAG,CAAC,kCAAmC,GAAa,EAAE,OAAO,IAAI,GAAG,2BAA2B,CAAC,CAAC;QACjG,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACxB,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC,iBAAiB,CAAC;IAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE1C,wFAAwF;IACxF,0FAA0F;IAC1F,yEAAyE;IACzE,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,CAAC;QAClC,OAAO,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC/B,OAAO;IACT,CAAC;IAED,MAAM,qBAAqB,EAAE,CAAC;IAE9B,MAAM,IAAI,GAAG,MAAM,iBAAiB,EAAE,CAAC;IACvC,IAAI,IAAI,EAAE,CAAC;QACT,GAAG,CAAC,yBAAyB,CAAC,CAAC;QAC/B,mFAAmF;QACnF,mBAAmB;QACnB,OAAO,CAAC,QAAQ,EAAE,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACvE,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IACjC,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,YAAY;IACnB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,gCAAgC;IACxF,CAAC;AACH,CAAC;AAED,IAAI,YAAY,EAAE,EAAE,CAAC;IACnB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACnB,GAAG,CAAC,UAAU,GAAG,EAAE,OAAO,IAAI,GAAG,EAAE,CAAC,CAAC;QACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

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"}