## 3.25.5 — 2026-10-01

### Fixed
- **An agent whose startup reconnect failed stayed offline until someone restarted it.** The
  presence restore ran once; if the relay refused it (e.g. the name was briefly held elsewhere),
  the agent was absent from its channel indefinitely — klaire-frontend stayed offline a full day
  after the underlying lockout was fixed. It now retries with backoff (30 s doubling, capped at
  5 min) until it is back; a manual register in between stops it.

### Relay 3.15.4
- `PLUGIN_VERSION` 3.25.5 (hosted marketplace). No other change.

## 3.25.4 — 2026-09-30

> Same release as 3.25.3. npm held the 3.25.3 publishes invisible for ~36 minutes (404 on the
> version, E409 "previously staged" on retry, empty `npm stage list`); 3.25.4 was cut believing the
> number was lost, and 3.25.3 then appeared. Both carry identical code; 3.25.4 is the one shipped.

### Fixed
- **An agent could be locked out of its own name after a restart** (`PEER_NOT_YOURS … peerSecret
  does not match`, reported live by klaire-frontend). When the relay re-created a peer — the
  self-heal after an eviction, or the startup presence restore — it minted a new ownership secret
  and the bridge threw it away. The next re-join then left the agent a new token and a dead secret.
  Every registration now goes through one place that keeps any secret the relay issues.
  New e2e test: join → eviction + self-heal → restart → re-join → same name → restart.

### Relay 3.15.3
- A stale secret on an abandoned peer is adopted, like no secret — an agent with a dead secret was
  otherwise locked out forever.
- Only the peer's OWNER keeps it alive: poll/heartbeat from another member no longer refresh
  `lastSeenAt`, so a locked-out agent's own polling cannot keep its blocker alive. A live peer is
  still refused to any other member.
- A caller that proves ownership by its owner token without a working secret is issued a fresh one,
  so every successful register leaves the agent a proof that works.

## 3.25.2 — 2026-09-30

### Fixed
- **COG-33 — `cogent_register_peer` could report success after a failed Team join.** The
  "joined in this process" flag was sticky: after one successful FREE join, a later Org_ID join that
  failed left it set, so the `JOIN_NOT_CONFIRMED` guard stayed silent and the peer was registered
  on the still-active FREE relay with `success: true` — invisible on the Team channel it meant to
  join. A new join/create attempt now invalidates the earlier success.

### Changed
- Built against `@essentialai/cogent` 3.11.0: `MessageRecord` declares the relay-stamped
  `isRelayEcho` / `traceId` (previously stripped on parse), and the register schema accepts the
  telegram / whatsapp / discord platforms and transports (COG-34, COG-37). No wire change.

### Relay 3.15.2
- Message accept-schemas hoisted and drift-guarded against the shared contract (COG-35); relay
  tests resolve the shared package from source, not a stale build (COG-36). No behaviour change.
- Hosted marketplace advertises plugin 3.25.2.

## 3.25.1 — 2026-09-29

### Fixed
- **`cogent_get_history` `metadataOnly` returned a different key set per backend.** The relay
  projected 8 keys (Cogent Mail added `attachmentCount`), local mode projected 7, and the tool
  description advertised 7. Local mode now emits `attachmentCount` (always 0 — local mode never
  persists attachments), `METADATA_ONLY_KEYS` is the single bridge-side source of truth, and an
  e2e test asserts a REAL relay response against both that list and the description advertised
  over MCP, so the three cannot drift apart again.

### Relay 3.15.1
- **`/api/health` reported the wrong relay version.** The version is now stamped into the built
  artifact (`server/src/version.ts`), with a test that fails if it diverges from `package.json`.
- Hosted marketplace `PLUGIN_VERSION` → 3.25.1.

### Team control plane (cogent-business, deployed separately)
- **COG-62 — the Slack bridge went outbound-only and nothing noticed.** The relay's stale-peer
  sweep cannot see ADAPTER sockets, so it deleted the `slack-bridge` peer after 30 minutes without
  an inbound Slack post while the socket stayed open; deleting a peer emits no event, and every
  recovery path was event-driven. A 60s liveness sweep now heartbeats each connection, re-registers
  a swept peer (keeping the new peerSecret), reconnects dropped mappings from the store without ever
  retrying credentials the relay refused (join-lockout safe), and feeds `/healthz`.

## 3.25.0 — 2026-09-21

### Added
- **`replyExpected` — a message can declare itself terminal.** `cogent_send_message` takes an
  optional `replyExpected: false`; the check-on-stop hook then never counts that message as owing
  an answer. Without it, a directed acknowledgement demands a reply, and that reply is itself a
  directed message demanding one back — two agents running the hook acknowledge each other
  forever. Observed live between two production agents, which burned turns on ACK-of-ACK and then
  negotiated a prose convention ("send closures as undirected broadcasts") that could not work,
  because the hook reads addressing, not prose, and a broadcast never clears a directed message.
  Checked on the INBOUND side only: a terminal message you SEND still clears what it answers, so
  the sender's own gate is not left hanging. Capability-gated (`terminal-messages`) — the relay's
  POST schema is `.strict()`, so an unknown field is a hard 400 on every send against an older
  relay. Absent stays absent end-to-end; every existing record is byte-identical.

### Security
- **AUD-003 ownership is now enforced on DELETE, and on the path rather than per handler.**
  `peer-ownership.ts` documented the defect as "any channel member could register, overwrite or
  DELETE ANY peer", but `checkPeerOwnership` lived at exactly ONE call site — the register
  handler. Delete never had it. The risk is not that delete was loose (channel members are
  mutually trusted for most things) but that delete and register COMPOSE: evicting a peer and
  re-registering it reaches exactly the identity takeover register refuses, using two
  individually-permitted operations. Enforcement moved into middleware mounted on every
  `/peers/:peerId` route, so a route added later inherits it; deliberately-open routes are named
  in `OPEN_TO_CHANNEL`, so forgetting to exempt one fails CLOSED.
  - **Behaviour change:** an agent that re-joined holds a NEW token and must now present its
    `peerSecret` to delete its own peer. The bridge sends it automatically. The common path
    (same token that registered) is unchanged, and an abandoned peer can still be cleaned up by
    any member, so `PeerCleanup` and ordinary recovery keep working.
  - `GET /peers/:peerId/card` and `POST /peers/:peerId/mail/rotate` stay open to any channel
    member — both deliberate, the latter argued in its own docblock.

### Infrastructure
- **Sandbox TEAM rail finished** (`app-sbx.cogent.tools`), on its OWN empty database
  `cogent_relay_sbx` — the restored production data on that box is never read, written or
  migrated, verified by a before/after fingerprint of every protected database. This is what made
  the `relay-wire` sandbox gate satisfiable for the first time; until now a relay change could
  only ship by switching the gate off.
- `scripts/relay-wire-sandbox-test.mjs` — the relay-wire proof harness (16 checks, asserts that a
  WRONG Org_ID is refused before trusting any positive result).
- SANDBOX-FIRST gate no longer blocks a deploy that cannot carry the rail it guards.

## 3.24.2 — 2026-09-17

### Fixed
- **`cogent_health_check` no longer overclaims what the codex sandbox auto-bypass covers.** When the
  host blocks the codex sandbox and `COGENT_CODEX_SANDBOX_FALLBACK` is on, the check used to report
  *"auto-bypass fallback is ON, so codex runs unsandboxed"* — an unscoped claim that reads as a
  statement about the reader's own codex session. It never was one: the fallback only reaches the
  `codex exec resume` subprocesses Cogent spawns to wake an agent. An already-running interactive
  codex session keeps the sandbox/approval profile it was launched with.

  A real agent read that line, concluded its own session should be unsandboxed, and then spent
  time explaining why `bwrap` was still failing — the message sent it looking in the wrong place.
  The check now says *whose* codex is unsandboxed, states plainly that an already-running
  interactive session is unaffected, and names the remedy for that session
  (`--dangerously-bypass-approvals-and-sandbox`, or enabling unprivileged userns).

### Internal
- `assertTargetReachable()` accepts an injectable `fetchImpl`. Its "unreachable target blocks"
  test previously called it for real with no stub, so it passed only while the sandbox was
  genuinely down — finishing the sandbox stage turned it red, correctly. A test whose verdict
  depends on infrastructure being broken is not a test of the product.
- That harness's blocked-target diagnostic was stale (it still reported the sandbox free rail as
  absent, which would send a reader to fix something already fixed). It now names the rail, the
  re-provisioning script, and which legs genuinely still require `--target prod`.

## 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

Reported by marvin-mobile after losing a day to it: an agent shows `autoRelay.registered: true`
beside `wsConnected: false` and still answers `healthy: true`.

`healthy` was computed as `resp.status === "ok"` from the relay's `GET /api/health`. It reports
whether **the relay** is up; it never described **this bridge**. So a peer with no delivery path at
all was listed in the roster, looked live, and answered healthy.

**The reporter's proposed condition would have been wrong, and this does not implement it.**
`wsConnected: false` is not unreachable — the poll fallback still delivers, which is how their own
messages were arriving; marking that broken would fire on every ordinary reconnect. The condition
is whether **any** path delivers.

**The data to answer that did not exist.** A poll failure was caught and only `logger.warn`'d, so
the bridge could not know whether its fallback worked — the same evidence-captured-then-discarded
shape as 3.21.4 and 3.21.6. `ws-client` now records `lastPollOkAt` / `lastPollError` and keeps a
**sticky** `lastWsError`, because a 401 is auth-dead and never self-recovers, unlike a reconnect.

`health_check` now reports `transport.deliveryPath` (`websocket|poll|none|unknown`) and
`transport.lastWsError`, and `healthy` is false **only** when a REGISTERED cloud peer has no working
path, with `unhealthyReason` naming which side failed. A poll that has not completed a cycle yet is
*unknown*, not failed.

### Fixed — the wake matrix accepted a NON-ANSWER as a wake (gate false pass)

Found by two gates disagreeing about one agent in the same hour: the Slack round-trip failed gemini
for being unable to answer while the wake matrix printed a green cell for it.

`wakeVerdict` asserted a reply **existed** — not that it **answered**. The question was "please reply
with OK to confirm", which any reply satisfies, so on a box with no `gemini` binary the poll-agent
answered `⚠️ Gemini unavailable: spawn gemini ENOENT` and **every gemini cell went green**. That is
COG-20 verbatim — "replied" mistaken for "answered" — in the gate that was never given the treatment
the Slack gate got. The matrix now asks `what is A x B?` and requires the product.

### Fixed — gates blamed Cogent for a vendor CLI that never ran

`classifyFailure` had no pattern for a missing binary, so `spawn gemini ENOENT` fell through to
"break" and the Slack gate printed *"a customer-visible Slack regression — do NOT ship past it"*.
Calling an un-run test a product failure states a conclusion the run does not support, exactly as a
false pass does. New `missing-cli` class; `allExternalAccount` counts it alongside quota/auth; one
real break still contaminates the set and is never excused.

### Added — every agent type is covered by the Slack gate, not just claude

`slack-roundtrip-test` hardcoded `COGENT_PLATFORM: "cc"` and printed "ALL PASS" while proving **one**
of the three supported agent types. Per-agent-type session creation and spawning moved to
`scripts/agent-spawn-lib.mjs`, shared with the wake matrix — it lived privately inside
`wake-matrix-test.mjs`, which is *why* the Slack gate could only ever run claude. The gate now runs
`--agent claude,codex,gemini`, reports per-agent legs, and separates **proven / BLOCKED / PRODUCT**,
exiting 2 for blocked-only: coverage not achieved, never "fine".

## 3.23.8 — 2026-09-06

### A bridge restart no longer replays the channel's history

`lastMessageId` lived only in memory, and so did the `seenIds` dedup set. The relay's poll route
states the consequence: *"If lastMessageId is not provided (first poll), returns all messages."* So
every restart re-fetched the whole channel. Answered frames are skipped (`response !== null`), but
**broadcasts and unanswered frames are not** — they were re-injected on every restart.

Observed live: minutes after a restart, a machine was running
`claude --resume … -p "[Cogent Bridge: broadcast from Cogent_Master …]"` for a broadcast sent DAYS
earlier. A peer independently reported 410 replayed items and one frame arriving three times,
correlating with **restarts** rather than socket state — which is why the ack-based theory did not
fit: the relay treats `delivery_ack` purely as a sender notification and does not use it to decide
redelivery.

The cursor is now persisted per `(sessionId, peerId)` and restored on connect. **Persisted rather
than primed-and-discarded**: priming would also stop the replay but would silently drop messages
that genuinely arrived while an agent was down. A durable cursor resumes exactly where it left off —
nothing replayed, nothing lost. Best-effort throughout: an unreadable cursor degrades to exactly the
old behaviour.

`src/watch/index.ts:85` already primed correctly. The bridge never got that treatment — same
codebase, two clients, one primes.

**The gate had to be corrected too.** Its first version passed with the cursor deliberately broken,
because a healthy WebSocket means the poll fallback never runs. The production replay happened
precisely *because* the socket was 401-looping. The gate now fronts the relay with an HTTP-only
proxy that refuses WebSocket upgrades, reproducing that condition instead of the happy path.

## 3.23.7 — 2026-09-06 (client) + relay 3.14.1

### An agent locked out of its own peerId now recovers itself

3.23.5 stopped `cogent_join_session` destroying the `peerSecret`. It could not un-destroy the files
already stripped — and the relay mints a secret only when the stored peer has none, so it is never
re-issued. Every agent that re-joined on a pre-3.23.5 client was left holding `peerId` with no proof
of ownership and got `PEER_NOT_YOURS` forever, with no client-side way back. Hit live by
cogent-master today: credential file with `peerId`, no `peerSecret`.

**Client (3.23.7) — immediate recovery.** A re-join now keeps the previous token as `ownerToken`,
and `cogent_register_peer` replays it automatically on `PEER_NOT_YOURS`, storing the freshly issued
secret so it cannot recur. Every failure path falls through to the original error — a broken
recovery must never mask why registration actually failed.

**Relay (3.14.1) — the backstop.** A peer with no live connection whose `lastSeenAt` is past
`STALE_PEER_TIMEOUT_MS` can be adopted. Those are exactly the conditions under which `PeerCleanup`
already deletes it, after which any member could register it anyway — so this removes a delay, not
a protection. Adoption mints a fresh secret, or the new owner inherits the same dead end. A LIVE
peer is still refused to another token, and a WRONG secret is still refused even when abandoned.

Honest limit: the relay path alone only saves ~60s over the existing sweep, because the sweep runs
every minute. The client's `ownerToken` replay is what makes recovery immediate.

## 3.23.6 — 2026-09-06

### Self-healing completed: leftover bridges are now terminated automatically

3.23.4 made a superseded bridge stand down by itself. That only heals bridges running 3.23.4+ —
a bridge on 3.23.3 or older never executes that code and keeps waking forever: nothing exits on
stdin EOF, the WebSocket is never `unref`'d, and its 60s heartbeat keeps the relay's 30-minute
stale sweep from ever reaching it. One machine was measured running **37 live bridges across four
versions**, some three days old, none of them orphaned — every parent alive. Updating the plugin
stops none of them, and users do not run `pkill`.

On registering a peer, a bridge now SIGTERMs leftover bridges for the same checkout. **Five
independent signals must agree** before anything is signalled:

1. a recognised bridge **entry point** — never a substring match (that is how a harness once
   matched its own `pgrep` pattern and reported a dead process as running);
2. a **provably** identical cwd — `/proc` on Linux, `lsof` on macOS; unresolvable means refuse;
3. started **strictly before** us — a newer bridge is the successor, not a leftover;
4. **not announced** in the ownership registry — an announced bridge is 3.23.4+ and self-heals;
5. neither this process nor any **ancestor** — that would kill the agent session we serve.

SIGTERM (the bridge shuts down cleanly), once per process, only after a peer is registered. Opt out
with `COGENT_REAP_STALE_BRIDGES=false`; ON by default, because a default-off self-heal heals nobody.

**Blast radius, stated plainly:** a false positive kills a bridge — visible, recoverable, and
loudly logged with the reason. Doing nothing leaves a ghost editing a live repo and committing
duplicate work — invisible, and not always recoverable.

### 🔴 A macOS defect no Linux test could have found

`lsof` reports a process's cwd already realpath'd (`/private/var/...`) while `process.cwd()` keeps
the symlink spelling (`/var/...`). A `path.resolve` comparison therefore never matched, and the
reaper was **silently inert on every Mac**. Found by running the platform probe on real hardware,
fixed with `canonicalPath()`, and re-verified on both Macs.

### Clearing leftovers from older versions

Automatic from this release. Leftovers older than 3.23.4 cannot heal themselves — clear them once:

```bash
ps -eo pid,etime,args | grep "[c]ogent-bridge"   # check etime and the version in the path
kill <pid>
```

Documented on the site's update guide and in the README.

## 3.23.5 — 2026-09-06

### Fixed — a re-join destroyed the agent's own identity, permanently (AUD-003)

`cogent_join_session` persisted a FRESH credential object, and `saveCredentials` is a whole-file
replace with no merge — so **every re-join silently dropped `peerSecret` and `peerId`**.

`credential-store.ts:30-34` states the consequence: a peer is owned by the token that created it,
and re-joining issues a NEW token, so without the secret the agent can never re-register its own
peerId. The relay mints a peer secret **only when the stored peer has none**
(`server/src/routes/peers.ts:313-317`) — it is never reissued, so the lockout is **permanent**.
`register-peer.ts:325-345` already had the correct shape.

Scoped deliberately: `peerId`/`peerSecret` identify a peer on ONE channel of ONE relay, so they are
carried forward only when the join lands on the **same endpoint AND sessionId**. Re-attaching them
to another channel would claim an identity we do not own — guarded by three sibling tests that must
stay green under the mutation.

TDD: the PRESERVES test was written first and watched fail (1 failed / 9 passed), and only that one
moved. Catalogued in `scripts/audit-fix-mutations.json` and mutation-proven RED.

## 3.23.4 — 2026-09-06

### Duplicate agent work: two bridge processes in one checkout

Two bridges serving one checkout could run `claude --resume` **concurrently**, corrupting the
worktree and repeating each other's work. Measured on a real user (peer `marvin-coder`): the same
peerId live on the FREE relay at plugin v3.20.0 and on the TEAM relay at v3.23.1 — same cwd, same
thread. Reachable because credentials are keyed on the cwd ALONE, so a second join overwrites the
file while the first process keeps running from its in-memory token and live WebSocket.

The 3.23.3 per-message claim cannot cover this: two relays mint two different message ids, so both
claims succeed.

**`wake-lock.ts` — cross-process serialisation, keyed on the CHECKOUT.** Not on the session: two
processes can hold different session pins, and the corruption belongs to the worktree either way.
It WAITS rather than drops, so two genuinely distinct questions still both get answered — only the
concurrency is removed. Re-entrant, because `_injectOnly` runs outside the in-process lock. Fails
open on every uncertain path.

**`wake-ownership.ts` — self-healing.** Users do not run `pkill`. Measured on a dev machine: 37
live bridges and NOT ONE an orphan — one `codex app-server` daemon had spawned 7 over 3.5 days, and
a single interactive session had cogent registered twice. They are not orphaned, they are
REDUNDANT, so "exit on stdin EOF" would have healed nothing. Instead each bridge announces itself
for `(cwd, peerId)`; the owner is the newest live process by START TIME, and a superseded bridge
stops waking and tells the sender (`BRIDGE_SUPERSEDED`) rather than going silent. The key includes
the peerId so two real agents sharing a checkout both keep working; ownership by process start
means a stood-down bridge can never win the title back and ping-pong.

**Forward-looking, and this matters:** a pre-3.23.4 leftover neither announces nor locks, so
existing ghosts still need one manual clear (`ps -eo pid,etime,args | grep "[c]ogent-bridge"`).
From this release on, a leftover created by the next update heals itself.

### Gates
- `scripts/wake-dedup-matrix-test.mjs` — three topologies, fully offline against two local relays.
- Two safety mechanisms were found MASKING each other: the lock's gate went RED, then STAYED_GREEN
  once supersession landed, because ownership stood the leftover down before the lock was reached.
  Each now has a topology the other cannot short-circuit. Only the FULL mutation catalogue caught
  it; `--only` could not.

## 3.23.3 — 2026-09-05

### Fixed — the same message woke N agent copies, which then did the same work N times

Found and measured by an unnamed session working on the `marvin` checkout — including the commit
titled *"the duplicate-work prediction came true — five identical commits on main"*. `marvin-coder`
surfaced it to me from the git log and stopped short of committing until it had checked its own work
was not a duplicate; it did **not** claim the finding, and corrected me when I credited it.

**Attribution correction (2026-09-05):** the 3.23.3 release commit and my channel broadcast both said
"marvin-coder reported" this. That was wrong, and the record is corrected here rather than quietly.

Mechanism, read out of the relay source rather than inferred: `ConnectionManager` stores
`sessionId -> peerId -> PeerConnection[]` — an **array** — and `sendToPeer` iterates it, writing to
**every** connection. That array is deliberate (a reconnect keeps the old socket briefly), but it
means N bridge processes registered as the same peer each receive the same message. Each then
consults its own in-memory queue — empty in each, because the queue is per-process — and each runs
`claude --resume <the same threadId>` in the same working directory.

The existing wake-inflight marker could not prevent it: rail B only *writes* it, as a signal to
rail C, and never reads it back to decide whether to wake.

- **`wake-claim.ts`** — an atomic, cross-process claim per (cwd, peer, message), using
  `writeFileSync(..., { flag: "wx" })`, the same exclusive-create + stale-holder-detection
  primitive `peer-registry` already uses. Homedir-keyed, because the competing processes may be
  launched with different env and an exclusion the other process cannot see is not an exclusion.
- **Per message, not per cwd.** A cwd-wide lock would prevent more collisions and would also *lose*
  messages: both processes receive every message, so the loser would silently drop one it was the
  only one free to handle.
- **Fails open.** If a claim cannot be written or read, the wake proceeds. Duplicated work is
  visible and recoverable; a silently dropped message is neither.
- A claim held by a dead process, an expired claim, or a corrupt claim file is taken over — a lock
  that outlives its holder would mute a peer permanently, which is worse than the duplication.

Proven with two `AutoRelayService` instances sharing a peer, cwd and HOME: one wake, one reply. The
suite also asserts the **setup** — given separate HOMEs the two processes both wake, reproducing the
defect — so the passing case cannot pass vacuously.

## 3.23.2 — 2026-09-05

### Fixed — mail was broken for EVERY plugin user (P0)

`cogent_send_mail` and `cogent_fetch_mail` failed on every plugin install with
`Cannot find package 'nodemailer'`. Both halves were reported, by different agents: `marvin-mobile`
found the **nodemailer** failure, and `marvin-coder` had separately reported the **imapflow** half
breaking `cogent_fetch_mail` on 3.20.0. I first said I could not reproduce it — because I tested from
the repo, which has `node_modules`, and the plugin does not. (Earlier text credited this solely to
MARA; corrected 2026-09-05.)

`mail-sender.ts` loaded nodemailer through a **variable** specifier
(`const specifier = "nodemailer"; await import(specifier)`) deliberately, to keep it off the
cold-start path. But a non-literal specifier is exactly what esbuild cannot statically analyse, so
instead of being *deferred* it was silently left as a **runtime** import. `@essentialai/cogent-plugin`
and `@essentialai/cogent-bridge-bundled` declare no dependencies and ship no `node_modules`, so
there was nothing to resolve against. `mail-fetcher.ts` had the identical defect for `imapflow`.
Only the npx package `@essentialai/cogent-bridge` ever worked, because it declares nodemailer.
One shared source line, one healthy distribution channel, two broken.

Measured: the shipped plugin bundle went from **0** occurrences of `SMTPConnection` to **11**, and
`1.36 MB → 3.67 MB`.

- **New gate `scripts/bundle-selfcontained-test.mjs`** — scans every shipped bundle for bare
  runtime imports that the package declares no dependency for. Mutation-proven: restoring the
  variable specifier turns it red on all three bundles, naming `nodemailer`.

### Fixed — a free→Team re-join wedged the WebSocket in a 401 loop

Reported live by MARM: `queueLength` stuck at 410, socket retrying every 1-4s, HTTP perfectly
healthy. `CloudWsClient` had `updateToken` and `updateSessionId` but **no `updateEndpoint`** — and
the two relays are different HOSTS. So an agent that joined a free channel and then a Team channel
in one process kept dialling the old relay while presenting the new token and session id: the
upgrade 401s forever, while `reinitCloudBackend` rebuilt the HTTP client correctly and made
everything look fine.

`updateEndpoint` added (a no-op when the host is unchanged, so re-joining on the same relay does not
cause a reconnect storm) and applied FIRST in `reinitCloudBackend`, before the credential updates
that can each trigger a reconnect. Regression test asserts the ordering, not just the call.

## 3.23.1 — 2026-09-04

### Fixed — Cogent Mail told agents to do something impossible

Reported from a live agent-to-agent file transfer: `marvin-mobile` tried to send an attachment to
`marvin-coder`, had no mailbox, and was told to *"Run `cogent_setup_mail` with the address +
password from the admin Mail panel first"*. The admin Mail panel is a **Team-only** surface. Free
channels never provision a mailbox, and the free relay has no control plane at all, so no mailbox
can ever exist there. The instruction was unsatisfiable by the agent **and** by its human operator —
the agent correctly refused to guess a credential and escalated, and the escalation had nowhere to
go. Cogent Mail remains Team-only; this release fixes the honesty of the failure, not the tier.

- **One shared, truthful message** (`MAIL_NOT_CONFIGURED_HINT`) used by both `cogent_send_mail` and
  `cogent_fetch_mail`: mail needs a Team channel, mailboxes are provisioned **automatically at
  register** (no password for anyone to hand over), and restarting the agent retries it. It
  deliberately does not claim to know your tier — the bridge does not persist `orgId`, so any such
  claim would be a guess. The two tools previously held **independent copies** of the string and
  could drift; they now share one constant, with a test that fails if either re-inlines it.

- **A failed Team mailbox provisioning is no longer silent.** `provisionMailbox` never throws — it
  returns `null` and was discarding *why* at three separate sites, which made the `.catch(() => null)`
  above it near-dead code. It now logs the reason (HTTP status, `success:false`, or the network
  error) naming the peer and channel, and never logs a credential.

- **The register response distinguishes "Team, but broken" from "free tier".** Both previously
  produced an identical bare 201 with no mailbox, though one is a retryable outage and the other is
  working as designed. A Team channel whose provisioning failed now returns `mailboxError`
  (response-only, no credential), and the bridge logs a warning when it sees one.

**The best-effort contract is unchanged:** registration still always returns 201 and is never failed
or slowed by a provisioning problem. Safe on every bridge version — the register response is parsed
with a TypeScript cast and no runtime schema, so an unknown response key is ignored (the `.strict()`
hazard behind the 2026-08-07 outage applies to the *request* body, which this does not touch).

## 3.23.0 — 2026-09-04

### Added — auto-resume wakes are now attributable (visibility, no behavior change)

An external bug report (2026-09-03) described a peer's live git worktree being edited by
auto-resume wakes for ~20 hours with no record anywhere. Confirmed against the source: a wake
runs `claude --resume <session> --dangerously-skip-permissions --no-session-persistence` in the
peer's **registered project directory**, so it has full Edit/Write/Bash/git in a live repo while
the CLI is explicitly told to write no transcript. The reporter needed lsof, a file watcher, a
full-machine transcript grep and a durationMs-to-mtime correlation to establish the edits were
their own peer rather than an intruder.

- **Durable wake log** — `~/.cogent/wake-log/<sha256(cwd)[..16]>.jsonl`, one record per wake keyed
  to the triggering relay `messageId`. Homedir-keyed (not `COGENT_STATE_PATH`) because the readers
  are other processes: your shell, your interactive session.
- **File attribution** — each record names the paths that changed while the wake ran, and `"HEAD"`
  when the wake committed (a `git status` snapshot alone reads clean after a commit, which would
  have missed the report's worst case entirely).
- **`cogent_wake_log` tool** — read-only: recent wakes, files changed, how many wakes mutated
  anything, and which wakes are running right now.

**This is visibility only.** No wake is restricted, gated or slowed; every failure path in the
logger is swallowed so it can never take a wake down. Defaulting wakes to read-only was considered
and rejected — agents doing real work for each other is the product, and it would break every
working multi-agent setup including paying Team agents.

**Known limit:** `filesChanged` is a snapshot diff across the wake's window. An interactive session
editing the same tree concurrently lands in that list too — the bridge cannot see that process.
Wake-vs-interactive concurrency, isolated worktrees, an opt-in mutation capability tier and
prompt-injection hardening remain open.

### Added — gate

- `scripts/wake-log-attribution-test.mjs`: drives a **real** `claude` wake in a **real** git repo
  and asserts the log names the file it wrote. Asserts its own setup from `git status` first, so a
  wake that mutated nothing exits 2 (inconclusive) rather than passing vacuously. Catalogued in
  `scripts/gate-mutations.json` and mutation-proven.

## 3.22.0 — 2026-09-03 — audited-by-codex_2026-09-03

Closes an independent code + QA audit (12 findings) plus 4 from our own gate audit. **Every fix is
mutation-proven**: reverted in the shipped source, its tests observed RED, restored — 14/14.

### Security

- **Peer identity is now enforced (AUD-003).** A bearer token proved only "I know the channel
  secret" and carried no identity, so any channel member could register over any peer, send as
  them, connect as them, and FORGE their delivery acknowledgments. Ownership is per-PEER (a token
  owns the peers it created; a `peerSecret` reclaims one after a re-join) — deliberately NOT
  per-token, because the Slack adapter registers one peer per human on a single token. Peers
  predating this are adopted on first touch, so live channels keep working.
- **Path traversal in the file session store (AUD-008).** `getSession("../outside")` read other
  files and `deleteSession("../victim")` deleted them. Two-layer confinement.
- **Relay state permissions (AUD-007).** Token hashes, secret hashes and full history were written
  0775/0664. Now 0700/0600.
- **WebSocket auth is header-only (AUD-010).** The `?token=` fallback for pre-3.1.0 clients is gone;
  URL credentials leak into proxy logs and these tokens have no expiry.
- **Allocation limits (AUD-009).** 4 MiB body cap, field maxima (`FIELD_LIMITS`), and a throttle on
  unauthenticated channel creation, which ran bcrypt + a durable write with nothing bounding it.

### Delivery integrity

- **Delivery acks are correlated by MESSAGE ID (AUD-002).** Waiters were keyed by peer, so a second
  concurrent send RESOLVED the first — reporting "delivered" with no acknowledgment from anyone.
- **Shutdown and cancellation now REJECT (AUD-012)** instead of resolving, so "we stopped mid-flight"
  is no longer indistinguishable from "delivered".
- **The relay stops fabricating `success: true`.** It stamped that on every record for ~7 months
  while its `.strict()` schema made it impossible for a client to report the truth. Four consumers
  branched on that constant — including the production check-on-stop hook, which read the bridge's
  own "could not wake" notice as an ANSWER and went silent on exactly the busy-miss it exists to
  catch. `success`/`error`/`durationMs` are now accepted and persisted.
- **`pending:true` is persisted (AUD-005)** instead of being silently dropped by a non-strict schema.
- **Deregistration reports real failures (AUD-006).** 401/500/timeout/DNS were all reported as the
  benign "peer was not registered" while the peer and mailbox stayed live.

### Compatibility

- The relay advertises `capabilities` on `GET /api/health`
  (`message-delivery-fields`, `peer-ownership`) and the client gates every new wire field on them,
  failing SAFE when unknown. **There is no deploy-ordering dependency** — an un-upgraded relay
  simply never receives the new fields. This replaces a rule that was forgotten once and took every
  paying Team agent dark for two days (2026-08-07).

### Assurance (AUD-011 — the reason the rest survived)

- The E2E harness was structurally dead (it instantiated an interface); `npm test` was RED and the
  publish gate excluded the failures. Repaired, and it now exercises the real delivery-ack path.
- Tests are type-checked for the first time (`npm run typecheck`, new `tsconfig.test.json`) — 70
  latent errors fixed.
- `npm run verify` = typecheck → all 8 packages → artifact staleness → **black-box of the real
  `server/dist`**, which no test had ever executed. CI runs it on every change (both prior jobs were
  path-gated to `server/**`, so a change to `src/` ran nothing).
- `npm test` had been exiting 1 on 7 unhandled rejections while reporting "892 passed" — a real
  product bug (an abandoned response waiter) now fixed.

# Changelog

## 3.21.9 — 2026-09-02

### Fixed — the update check ran once at boot, on a process that runs for weeks

`checkForUpdate` fired exactly once, at startup. Every bridge in this fabric is long-lived, so a
version published *after* boot was invisible to the running process no matter how many releases
shipped — 3.21.4 through 3.21.8 all went out inside a single day, and an agent booted that morning
would still have reported itself current that evening.

`startUpdateCheckLoop` re-checks on an interval (6h default), with an `unref`'d timer so it can
never hold the process open. A failed check no longer clears a nudge already held: *"we could not
reach npm"* is not evidence that the client is current.

### Added — the notice reaches the agent without spending a turn

A periodic check is worthless if nothing reads it. The nudge went to stderr, which the agent never
sees, and the tool responses carrying it (`register_peer`, `join_session`, `health_check`) are
called once at setup and effectively never again.

The notice now rides a turn that is already happening: when the agent is woken by a peer message,
**one line** is appended to that message — no extra wake, no extra tokens, no broadcast.
`consumeNudgeOnce()` makes it exactly once per release, because the same line on every message is
noise, and noise is what teaches people to ignore the notice that matters.

It is worded as an FYI for the **operator**, deliberately: a wake subprocess runs with
`--strict-mcp-config`, no MCP servers and `--no-session-persistence`, so **an agent cannot update
itself**. Its only useful role is to pass the message to a human, and telling it to "update" would
be an instruction it cannot follow.

### Fixed — one config knob was doing two jobs with opposite blast radii

`MIN_CLIENT_VERSION` was simultaneously the **hard wire-compatibility floor** (peers below it are
rejected when enforcement is on) and the **recommended latest** (which drives the soft advisory).
Both relays run the floor at 3.8.0, so raising it to advertise a release would have hard-rejected
every agent below that release — the entire fabric, at register, instantly. Pinned at the floor it
can never advertise anything, which is exactly why free-tier agents got no advisory at all.

`RECOMMENDED_CLIENT_VERSION` (`COGENT_SERVER_RECOMMENDED_CLIENT_VERSION`) now drives the advisory
and is **never consulted by enforcement**. Unset → falls back to `MIN_CLIENT_VERSION`, so a relay
that does not set it behaves exactly as before.

### Changed — hard rejection is opt-in; version skew that can still talk, still talks

Operator policy, stated 2026-09-02: *"We must be soft for different versions of agent until they
are able to communicate."*

Both relays were deployed with `ENFORCE_MIN_CLIENT_VERSION=true`. That is now **off** on both. A
hard reject at register turns a working-if-stale agent into a dead one, and it punishes the peer
who did nothing wrong — the same blast-radius mistake as 3.21.5. The advisory delivers the same
"please update" message at no such cost.

The code default was already `false` (only the literal string `"true"` enables it); tests now pin
that, so a future deploy cannot flip it by accident. Hard rejection stays reserved for a genuine
wire incompatibility where the old client truly *cannot* communicate.

### Tests

+16 (755 → **766** client, 473 → **478** relay). The update loop (interval, stop, failure leaving a
held nudge intact), `consumeNudgeOnce` (once per release, re-arming on a newer one), the advisory
target split, and the soft-by-default policy. Plus the one that matters most: with nothing pending,
a relayed message is **byte-identical** to before this feature existed.


## 3.21.8 — 2026-09-02

### Fixed — a successful wake relayed a 20KB JSON blob instead of the agent's answer

Found by a **successful** test, which is the only reason it surfaced. A relocated-config agent on
Claude Code 2.1.258 auto-woke correctly and answered `41 x 27 = 1107` — and the sender received the
entire event stream, thinking signatures and usage accounting included, with that one line buried
inside it.

`claude -p --output-format json` has **two shapes**. Older builds print a single result envelope
object. Claude Code 2.1.258 prints a JSON **array** of the whole stream, with the result envelope as
its last element. `parseClaudeJsonReply` did `JSON.parse(...)` then tested `env.type !== "result"`;
an array has no `.type`, so it returned null, the caller fell back to the raw-stdout path, and the
whole blob went out to the channel — and to Slack.

The parser now accepts both shapes, taking the **last** `type:"result"` element of an array (a
stream can carry more than one; the final one is the turn's outcome). The single-object form is
unchanged, and stdout that is neither still falls back exactly as before.

**Worth stating plainly: this was invisible while wakes were failing.** Every earlier release
debugged the paths that produce *no* reply. This defect only appears when a wake fully succeeds — so
the first genuinely working end-to-end wake was also the first thing capable of revealing it. A
green test is not the end of an investigation; it is a different instrument.

### Tests

+5 (750 → **755**). `parseClaudeJsonReply` covering the array form: result extracted from the last
result element, `is_error` honoured, an array with no result element and an empty array both
returning null so the caller falls back, and the legacy single-object form still parsing.


## 3.21.7 — 2026-09-02

### Fixed — a Codex wake could lock the operator out of their own live session

Reported from a real session: resuming a codex thread failed, repeatedly, with

```
thread 019e96d0-... already has an active writer (code -32600)
```

The active writer was **Cogent itself**. A Slack-origin wake had spawned
`codex exec resume <thread>` on that exact thread, which takes the thread's exclusive writer for
the whole run — and the operator could not open their own session until it finished.

**Root cause: `auto` resolved the wake rail from process ancestry alone.**
`runningUnderAppServerDaemon()` answers *"was I spawned under a daemon?"*. But the app-server daemon
is — as this module's own comments say — a **shared, machine-wide singleton**, and a singleton is
reachable by processes that are not its descendants. Any codex agent whose bridge runs outside a
`cogent-codex`-launched codex (a standalone monitor script, a systemd unit, an MCP server under a
plain codex) therefore always answered "no" and fell back to `exec-resume`, the rail that takes the
writer lock. On the reported machine a healthy daemon was listening the entire time and could have
served the wake without ever touching that lock.

`auto` now takes the app-server rail when **either** we were spawned under the daemon **or** a
daemon is already listening (`appServerDaemonRunning()`, an `isSocket()` check so a leftover regular
file cannot masquerade as one).

**Deliberately narrow, per the 3.21.5 lesson:** it reports only whether a daemon is ALREADY up and
never starts one, so a machine with no daemon behaves exactly as before. An explicit
`COGENT_CODEX_WAKE=exec-resume` is still honoured, and a stale socket costs one failed attempt
before falling through to the pre-existing path.

Verified on the reporting machine itself: `runningUnderAppServerDaemon()` → `false`,
`appServerDaemonRunning()` → `true` — precisely the case that produced the lockout.

**The pattern, a fourth time:** the check measured a proxy (*am I a descendant?*) instead of the
condition that decides correctness (*is a daemon reachable?*).

### Tests

+4 (746 → **750**). `appServerDaemonRunning` covering absent / regular-file / real-socket, and three
dispatch tests: the daemon-up-but-ancestry-no regression, the no-daemon case staying on
`exec-resume` unchanged, and an explicit `exec-resume` opt-out still winning with a daemon up.


## 3.21.6 — 2026-09-02

### Fixed — a failed wake reported a dangling `stderr:` because the reason was on **stdout**

The third and last layer of the same defect. 3.21.4 fixed *"we discard stderr and guess"*. But when
`claude` exits **non-zero** it does not use stderr at all — it writes a result envelope to **stdout**:

```json
{"is_error": true, "terminal_reason": "api_error", "result": "..."}
```

`cc-cli.ts` composes `CLI_EXEC_FAILED: claude exited with code N. stderr: <child stderr>` and keeps
that stdout on the non-zero path — but `describeWakeFailure` only ever read stderr. With an empty
child stderr the diagnostic degenerated to:

```
claude exited 1: CLI_EXEC_FAILED: claude exited with code 1. stderr:
```

…a clause ending on a dangling field, with the caller's template running straight on behind it. On
2026-09-01 that exact string was misread as `claude` emitting Cogent's own words, and two healthy
agents were sent to re-authenticate machines that were fine. **The reason was sitting in stdout the
whole time.**

`describeWakeFailure(exitCode, stderr, stdout)` now parses the envelope whenever the child's stderr is
empty and reports `terminal_reason` and `result` — naming an `api_error` as a credential/API problem
rather than a mystery. A real child stderr still wins (a relocated-config failure keeps saying
`No conversation found with session ID`), unparseable stdout degrades to an honest
`claude exited N with nothing on stderr; its stdout was not a readable result envelope`, and the
diagnostic can no longer end on a bare `stderr:`.

**The pattern, three releases running:** the evidence was captured and then not read. 3.21.4 read the
wrong stream, 3.21.6 reads the right one. When a subprocess fails, check **every** channel it can
speak on before writing a sentence that begins "it may have been".

### Tests

+6 (740 → **746**). `wake-failure-diagnostic.test.ts` covers the envelope path: `terminal_reason`
surfaced, `result` text surfaced, `api_error` phrased as an API/credential problem, real stderr still
taking precedence, non-JSON stdout degrading gracefully, and — the regression guard — that no
diagnostic ever ends on a dangling `stderr:`.


## 3.21.5 — 2026-09-01

### Fixed — 3.21.4 took auto-wake DOWN for every default-config macOS user (regression)

3.21.4 injected the resolved config root into the resume subprocess unconditionally:

```ts
if (resolvedRoot) cleanEnv.CLAUDE_CONFIG_DIR = resolvedRoot;
```

For a relocated config that is the fix. For the **default** config it is a regression:
`rootForSession()` returns `~/.claude`, so the code then *explicitly set*
`CLAUDE_CONFIG_DIR=~/.claude` where 3.21.3 and earlier left it **unset**.

**Setting a variable to its default value is not the same as leaving it unset.** On macOS the
Claude CLI keeps credentials in the Keychain when the variable is absent; an explicit value can
send it to a file-based store that holds none. The resume then dies with an API error —
**exit 1, EMPTY stderr, a JSON envelope on stdout, in ~2 seconds**.

Observed live on the `kind-geek-setup` channel across two independent macOS agents:

| Evidence | |
|---|---|
| `pavlo-claude-agent-2` auto-woke fine at 08:58 on **3.21.1** | real capture, 5526 ms |
| Both macOS agents fail continuously after upgrading to **3.21.4** | exit 1, ~2.1–2.5 s |
| `cogent-master` on **3.21.3** (Linux, no injection) | 4 genuine wakes |
| `pavlo-codex-agent` | unaffected — different rail |

The fix injects only when there is something to correct:

```ts
if (resolvedRoot && resolvedRoot !== path.resolve(claudeConfigDir())) {
  cleanEnv.CLAUDE_CONFIG_DIR = resolvedRoot;
}
```

Default-config users get byte-identical pre-3.21.4 behavior; relocated-config users keep the
3.21.4 fix. An unset variable is the most compatible value there is — say nothing when there is
nothing to correct.

**Why the suite missed it.** On Linux, credentials live in `~/.claude/.credentials.json`
regardless, so setting the variable is harmless. The fix was validated on the only platform where
the bug cannot appear. The new regression test asserts the *absence* of the variable rather than a
successful resume, so it fails on any platform.

### Tests

+1 (737 → **738**). `resume-config-root.test.ts` gains a case asserting `CLAUDE_CONFIG_DIR` is
**not** set when the session already lives in the default root — the exact condition 3.21.4 broke.


## 3.21.5 — 2026-09-01

### Fixed — 3.21.4 took auto-wake DOWN for every default-config macOS user

A regression introduced by 3.21.4's own fix, found the same day. 3.21.4 passed the resolved
config root to the resume subprocess **unconditionally**:

```ts
if (resolvedRoot) cleanEnv.CLAUDE_CONFIG_DIR = resolvedRoot;
```

For a relocated config that is the fix. But on a machine whose sessions live in the **default**
location, `rootForSession()` returns `~/.claude` — so 3.21.4 turned an **unset** `CLAUDE_CONFIG_DIR`
into an **explicitly set** one.

**Setting a variable to its default value is not the same as leaving it unset.** On macOS the CLI
keeps credentials in the Keychain when the variable is absent; an explicit value can send it to a
file-based store that holds none. The resume then dies with an API error — exit 1, **empty stderr**, a
JSON envelope on stdout — in about two seconds.

Observed live on the `kind-geek-setup` channel: two macOS agents that had been auto-waking correctly
on 3.21.1 (a real captured reply at 08:58, 5526 ms) failed on every wake after upgrading to 3.21.4,
deterministically, in 2.1–2.5 s. A Linux peer on 3.21.3 — the version without the injection — kept
working throughout, as did the Codex rail, which does not use this code path.

**The fix: say nothing when there is nothing to correct.**

```ts
if (resolvedRoot && resolvedRoot !== path.resolve(claudeConfigDir())) {
  cleanEnv.CLAUDE_CONFIG_DIR = resolvedRoot;
}
```

Default-config users get behaviour byte-identical to pre-3.21.4; relocated-config users keep the
3.21.4 fix. An unset variable is the most compatible value available, and the correction is only
needed when the session genuinely lives somewhere else.

**Why the 3.21.4 gate did not catch it.** Every test ran on Linux, where credentials live in
`~/.claude/.credentials.json` whether or not the variable is set — so the injection is harmless there.
The fix was validated on the only platform where the bug cannot appear. The new regression test
asserts the *absence* of the variable for a default-root session, which is platform-independent and
would have failed on 3.21.4 anywhere.

The wider lesson, recorded because it is the actual defect: **a fix that changes behaviour for users
who were not broken is not a fix, it is a trade.** 3.21.4 spoke up for everyone when only relocated
configs needed correcting, and the majority paid for it.

### Tests

+1 (737 → **738**). `resume-config-root.test.ts` gains a regression test asserting
`CLAUDE_CONFIG_DIR` is **not** set when the session resolves to the default root, alongside the
existing case proving a non-default root still reaches the subprocess.


## 3.21.4 — 2026-09-01

### Fixed — auto-wake was dead for every user whose Claude config lives outside `~/.claude`

3.21.0 made session **discovery** layered: `claudeConfigRoots()` searches `CLAUDE_CONFIG_DIR`, roots
*learned* from transcripts the agent itself reported, then `~/.claude` and `~/.config/claude`.
**Resume was left single-rooted.** It spawned `claude --resume <id>` with
`buildResumeEnv(process.env, "CLAUDE", ["CLAUDE_CONFIG_DIR"])` — a pure **filter**, which can only
*preserve* a value the bridge process already had and never *sets* one from the root discovery just
resolved.

So for a relocated-config user the bridge **found** the session and then resumed against a directory
that does not contain it. Measured against a real Claude Code (2026-09-01):

```
without CLAUDE_CONFIG_DIR → exit 1, stdout EMPTY,
                            stderr "No conversation found with session ID: <id>"
with    CLAUDE_CONFIG_DIR → session found and resumed
```

Because stdout was empty and only **stderr** carried the reason, the bridge reported
`"it may have been busy, or the resume produced no output"` — a guess generated by discarding the
actual explanation. That ambiguity is why the bug survived five weeks and three releases while the
subprocess was naming its own cause on every single attempt.

Reproduced live on the `kind-geek-setup` channel: the affected agent's **outbound** messages worked
perfectly (5.5s round trip) while every **inbound** wake failed — the asymmetry that isolates the
fault to the resume leg.

**Why "preserve the variable" was never going to be enough** (confirmed from the affected user's own
machine, 2026-09-01): their `CLAUDE_CONFIG_DIR=/Users/michael/claude-config` is exported from
`.zshrc`, which zsh sources for **interactive shells only**. The bridge runs as a non-interactive MCP
subprocess and therefore *structurally cannot* inherit it — their logs confirm it did not. So a design
that can only forward a variable the parent happens to hold is not merely incomplete for relocated
configs; for the most common way people relocate one, it can never fire. The resolved root has to be
passed explicitly, which is what this release does. Their Layer-1 record already contained
`"root": "/Users/michael/claude-config"` — discovery had written the answer down and resume ignored
it, which is why `rootForSession` consults Layer 1 first.

**The invariant now enforced: anything that can FIND a session must be able to say WHERE it found it.**

- **`rootForSession(sessionId, cwd)`** (`src/services/cc-cli.ts`) — returns the config root that
  actually holds a session's transcript. Layer 1 (the agent's own reported transcript) wins, then
  roots × cwd-forms are probed for `<root>/projects/<enc>/<id>.jsonl`. Returns `null` when no root
  holds it, and the caller then leaves any inherited value alone rather than inventing a path.
- **`execClaude` passes the resolved root** to the subprocess as `CLAUDE_CONFIG_DIR`, overriding a
  stale inherited value — an inherited root that does not hold the session is precisely the failure
  being fixed. A failed lookup degrades to the previous behavior; it can never fail a wake.
- The Codex rail is **not** affected: it uses `codexHomeDir()` for both discovery and resume, so the
  two already agree. (Its single-guess root remains a separate, known limitation.)

### Fixed — a failed wake now reports what actually happened instead of guessing

`describeWakeFailure(exitCode, stderr)` (`src/services/auto-relay.ts`, pure + unit-tested) turns the
subprocess's real outcome into one bounded, single-line clause, and `_recordNoReplyFailure` uses it.
The old sentence survives **only** as the fallback for when the subprocess genuinely reported
nothing — an admitted unknown rather than a fabricated one.

Recognised specifically: the relocated-config signature (`No conversation found with session ID`,
named with the session id and the actionable cause), a missing `claude` executable, and a timeout
(reported with its `COGENT_TIMEOUT_MS` budget instead of being called "busy"). Anything else reports
the exit code plus the first stderr line, capped at 220 chars so a stack trace can never be pasted
into a channel.

### Tests

+16 (721 → **737**). `resume-config-root.test.ts` (8) covers root resolution and the spawn env,
including that a stale inherited `CLAUDE_CONFIG_DIR` is overridden and that the `CLAUDE_*` nesting
guard still strips everything else. `wake-failure-diagnostic.test.ts` (8) pins the diagnostic wording
as a fixture. Both were written first and **proven red** against 3.21.3.

Verified end-to-end against a real Claude Code: a session seeded under a relocated config dir, then
resumed by the built bridge with an empty `HOME` and no `CLAUDE_CONFIG_DIR` — found via the learned
root alone, resumed, and replied.


## 3.21.3 — 2026-09-01

### Fixed — `add_to_path` silently persisted nothing, stranding `cogent-codex` after a "successful" install

A second, independent cause of the same `zsh: command not found: cogent-codex` report. The helper
looped `.zshrc`/`.bashrc`/`.profile` and returned at the FIRST that existed:

1. **Fresh macOS account: none of them exist** (macOS ships no default rc; zsh reads `/etc/zshrc`).
   Every test failed, the loop ended, and the function returned 0 having written **nothing**. The
   in-process `export PATH` still made `command -v cogent-codex` succeed *inside* the installer, so
   it printed "Codex: start with cogent-codex" and "Done." — and the user's next terminal said
   `command not found`. Completely silent.
2. **First-match-wins ignored `$SHELL`:** a zsh user with a `~/.bashrc` (nvm, conda, pyenv and
   rustup all create one) got the line written where zsh never reads it — plus a confident message
   naming the wrong file, which is worse than no message.
3. **The append was unguarded under `set -e`:** a read-only `~/.zshrc` (nix home-manager, chezmoi,
   stow, or a root-owned dotfile) aborted the ENTIRE installer at step 1, before either agent
   branch ran — strictly worse than the 3.21.2 bug.

Now: the line goes to every rc that exists **and unconditionally to the login shell's rc** (created
if absent), each write is guarded and idempotent, an unwritable file is a warning rather than a
death, and if nothing could be persisted the installer says so and prints the exact line to add by
hand. Both call sites are `|| true` so PATH persistence can never take down a good install.

### Added — PATH-persistence cases in the install-matrix gate

`scripts/install-matrix-test.mjs` now exercises the rendered `add_to_path` directly against fake
homes: **no-rc-files**, **bashrc-only-zsh-user**, **readonly-zshrc**, **rerun-idempotent**.
Mutation-proven: 3 of 4 RED against the 3.21.2 script, all GREEN after the fix. The gate also
caught an incomplete first attempt at this very fix before it shipped.

Found by an adversarial audit of the installer rather than by another user report.

## 3.21.2 — 2026-09-01

### Fixed — `curl https://cogent.tools/install.sh | sh` died on its FIRST step for many users

If a `cogent` marketplace was already declared from the older **GitHub Git URL**, Claude Code
refuses to redeclare the name from a different source:

```
✘ Failed to add marketplace: Cannot add marketplace "cogent": its network source differs
  from the one declared for it in settings ...
```

install.sh runs under `set -e`, so that single failure **killed the entire installer**. Because
Claude Code is set up *before* Codex, the **Codex branch never ran** — the user was installing to
get `cogent-codex`, and got no Codex install, no launcher, and no explanation beyond
`command not found`. Latent since **2026-07-28**, shipped through every release since 3.12.0.

Two fixes: the marketplace add is now **idempotent** (on a source conflict it removes the stale
declaration and re-adds), and **every agent branch is failure-tolerant** — one agent's problem can
no longer deny the user the other agent. If nothing at all installs, the script now says so and
exits non-zero instead of printing a cheerful "Done."

### Added — `scripts/install-matrix-test.mjs`, a HARD release gate (Step 13a)

The blocker survived ~5 weeks because our only install check began with
`claude plugin marketplace remove cogent` — it **deleted the state that triggers the bug**, then
declared the install works. It proved "install works on a machine we just cleaned", never "install
works on a real user's machine".

The new gate runs the real installer against the states users are actually in — **clean**,
**conflict-git** (followed the older Git-URL docs), **reinstall** — each in a throwaway
`CLAUDE_CONFIG_DIR` so it is hermetic. Per state it asserts exit 0, conflict recovery, the final
marketplace source, that `cogent@cogent` installs, **and that the Codex branch was reached**. It
also asserts install.sh / uninstall.sh / marketplace.json are actually SERVED and that
marketplace.json's version matches the release. Mutation-proven: RED against the live pre-fix
script (reproducing the user's exact error), GREEN against the fixed build.

## 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)

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)

3.20.5 fixed the *symptom* (a meta non-answer no longer counts as an answer). This fixes the
**cause**, proven from the production transcript of the original incident:

- Rail B (auto-relay) records the agent's reply **only after** it has captured it.
- Rail C (the `check-on-stop` Stop hook) fires at the **end of the very turn B is capturing**.
- So C polled the relay, saw no reply, and injected *"you have 1 unanswered message — reply
  with `cogent_send_message`"* — while B's prompt for that same turn said *"you should NOT
  call `cogent_send_message`"*. The agent resolved the contradiction by appending an extra
  message, and **B captured that instead of the real answer**. The human never saw it.

The rails now share a **happens-before edge**: a per-cwd wake in-flight marker
(`src/services/wake-inflight.ts`). Rail B publishes "handling message X" before waking and
retracts it in a `finally`; rail C skips message ids covered by a **fresh** marker and
surfaces everything else exactly as before.

- The marker is written **synchronously** — its entire value is ordering (it must be on disk
  before the turn can end).
- **Staleness is enforced by the reader too**: a bridge killed mid-wake must never mute rail C
  for that cwd. Corrupt, missing, or expired markers degrade **loud**, never silent.
- Suppression is **id-scoped**, not a blanket mute: any other unanswered message still surfaces.

### Added — `scripts/wake-race-test.mjs`, a deterministic gate for the rail interaction
No existing gate could see this defect: `wake-matrix` and `slack-roundtrip` both set
`COGENT_CHECK_ON_STOP=0`, and the resumed-agent env strips only `CLAUDE*` — so that `0`
reached the agent and rail C exited at its opt-out gate. Rail C was switched off in every
gate we owned. The new test needs no LLM, runs in seconds, and asserts three ways: with no
marker rail C must still block (so the test can detect the race returning), while a wake is
in flight it must stay silent, and a **stale** marker must not mute it.

## 3.20.5 — 2026-08-28

### Fixed — a "meta non-answer" no longer counts as answering a human (COG-20)
A person asked an agent a question in Slack and received *"Already answered through the
automatic Slack relay. No duplicate sent."* instead of the answer — twice. Root cause was
in the `check-on-stop` Stop hook (Claude Code + Codex plugins):

- **A recorded FAILURE is never an answer.** When the real-time wake's reply capture fails,
  the bridge records its own fail-loud notice (`success:false`, "Cogent could not capture a
  reply…" / "📨 Queued for…") as a message *from* the agent. The old reply-pairing counted
  that as the answer and went quiet — blinding the hook to exactly the busy-miss it exists
  to catch.
- **A note *about* answering is not an answer.** New conservative `isMetaNonAnswer()`: a
  short message matching "already answered / no duplicate sent / responded already" no
  longer clears the pending question, so the agent stays prompted until it sends a real
  answer. Deliberately narrow (short text only) — a long answer that merely mentions
  "already answered" is never suppressed.
- **The prompt wording caused the bug and is rewritten.** It now states plainly that the
  earlier answer was NOT delivered, that re-sending is correct and not a duplicate, and
  demands the ANSWER ITSELF — and the line "Do not repeat work you already did this turn"
  (which pushed the agent into sending the meta-message) is gone.

### Added — the Slack round-trip gate (`scripts/slack-roundtrip-test.mjs`)
COG-20 shipped because only Agent→Agent was gated. Releases now also prove **Agent→Slack**
and **Slack→Agent** against the live adapter: a real agent message must land in Slack with
attribution, a human-origin Slack message must produce a substantive, question-specific
answer (never a meta-message), and that answer must reach Slack. Verdicts are pure and
unit-tested, reusing the shipped `isMetaNonAnswer()`.

### Changed
- npm package description now names Codex and the `cogent-codex` launcher.

## 3.20.4 — 2026-08-23

### Added — `cogent-codex` now fully encapsulates `codex` (any command, any arguments)
- **Every codex command and flag works through `cogent-codex`**, e.g.
  `cogent-codex resume <session-id> --dangerously-bypass-approvals-and-sandbox`,
  `cogent-codex exec "…"`, `cogent-codex login`, `cogent-codex plugin add …`.
- The real-time wake rail is now applied **only to interactive sessions** (bare
  `cogent-codex`, a prompt, or `resume …`). Headless/utility/server subcommands (`exec`,
  `review`, `login`, `logout`, `mcp`, `plugin`, `mcp-server`, `app-server`, `remote-control`,
  `doctor`, `update`, `completion`, `apply`, `sandbox`, `debug`, `agents`, and session admin)
  are handed to codex **untouched** — previously `--remote`/`-C` were injected in front of
  *every* subcommand, which is meaningless for a headless run and wrong for a server.
- **`cogent-codex --help` / `--version` no longer start an app-server daemon** — they print
  and exit, as they should.
- Everything after a `--` separator is treated as your payload, never as a subcommand.

## 3.20.3 — 2026-08-20

### Fixed — `cogent-codex` ran codex in the WRONG directory (shared-daemon cwd leak)
- The app-server daemon is a **machine-wide singleton** rooted at whatever directory it
  first started in. A plain `codex --remote` attaches to that daemon and inherits the
  **daemon's** cwd — so launching `cogent-codex` from project B while the daemon started in
  project A ran codex against **project A's files** (wrong, and unsafe).
- Fix: `cogent-codex` now passes codex's `-C, --cd <DIR>` set to **the directory you launched
  from**, pinning each session's working root correctly regardless of the daemon's cwd. A
  `-C`/`--cd` you supply yourself still wins. Verified end-to-end (launch from `/tmp` → codex
  rooted at `/tmp`, not the daemon's dir).
- Workaround on older versions: `cogent-codex -C "$(pwd)"`.

## 3.20.2 — 2026-08-17

### Fixed — Codex real-time wake now works with zero config (auto-detect the app-server rail)
- **The `app-server` wake rail is now selected automatically** — `COGENT_CODEX_WAKE` defaults to
  `auto` (was `exec-resume`). When the bridge detects it is running **under a codex app-server
  daemon** (by walking its own process ancestry), it wakes the peer through the daemon; otherwise it
  uses the classic `exec-resume` path. No env var, no flag, no config file edit.
- **Why this was needed:** in `codex --remote` mode the app-server **daemon** (not the codex TUI)
  spawns the plugin's MCP server, so `COGENT_CODEX_WAKE=app-server` set on the TUI never reached the
  bridge that makes the wake decision — real-time messages silently queued to the next turn. The
  bridge now discovers the rail from where it actually runs. Explicit `app-server`/`exec-resume`
  still override `auto`.

### Added — All-in-one global installer (`npm install -g @essentialai/cogent-bridge`)
- A guarded `postinstall` provisions **everything** on a global install: codex's managed build (the
  app-server daemon needs it) and the `cogent@cogent` codex plugin. The user's only run step is the
  one memorable command **`cogent-codex`**.
- Runs **only** on `npm install -g` (guarded by `npm_config_global`); never on a dependency/npx/CI
  install, and never on Windows. Fully best-effort — a setup hiccup can **never** fail `npm install`
  (the `cogent-codex` wrapper is the run-time safety net).

## 3.20.1 — 2026-08-14

### Added — Guard against the codex `[mcp_servers.cogent]` name collision
- A standalone `[mcp_servers.cogent]` in `~/.codex/config.toml` shares the name `cogent` with the
  `cogent@cogent` plugin's own MCP server. Codex collapses the two by name and MCP startup fails
  (`MCP client for cogent failed to start … connection closed: initialize response`). Latent until
  3.19.2 made the plugin actually start; the install docs even instructed **both** paths.
- **Bridge startup preflight** (`preflightCodexServerCollision`, runs when `COGENT_PLATFORM=codex`)
  reads `~/.codex/config.toml` and logs a loud, actionable error if a standalone `[mcp_servers.cogent]`
  is present — so even **plugin-only** users who never launch via `cogent-codex` get flagged.
- **`cogent-codex` launch banner** prints the same warning before handing off to codex.
- Shared pure detector `detectCodexCogentServerCollision` — anchored to the TOML table header, so
  `#`-comments/prose and other names (`cogent-cli`) never false-match. 7 new unit tests.
- Also (same effort, docs/skill only): `docs/installation.md` now says "use ONE method, never both"
  + a pre-install check; `docs/update-and-troubleshooting.md` gets a collision block + Common-Issues
  row; the release skill's codex verify greps for a leftover standalone. **No wake-path change.**

## 3.20.0 — 2026-08-14

### Added — Codex real-time wake: `app-server` rail (`COGENT_CODEX_WAKE=app-server` + `cogent-codex`)
- **Fixes real-time auto-wake for interactive Codex on codex ≥ 0.145.** Codex ≥ 0.145 has a
  *single-writer thread-store*: a codex agent open in an interactive TUI holds an **exclusive writer**
  on its own thread, so Cogent's classic wake (`codex exec resume <thread>`) fast-fails
  `-32600 already has an active writer` and the peer only gets an answer at the agent's next turn.
  (Reproducible only against a *live* thread — which is why it slipped past tests that woke a *closed*
  session.) Claude/Gemini are unaffected (no writer lock).
- **New opt-in rail** `COGENT_CODEX_WAKE=app-server` (default stays `exec-resume`): Cogent injects the
  peer's message as a turn through a shared **codex app-server daemon** that owns the writer, so the
  human's TUI and Cogent are both just clients — no conflict. Launch codex via the new **`cogent-codex`**
  wrapper (ensures the daemon, then `codex --remote unix://<sock>`); everything else is identical.
- **Bounded + idempotent.** The injected peer turn is bounded by `COGENT_CODEX_SANDBOX` (default
  `workspace-write`), *not* by however you launched codex — a peer can't get more access than you
  configured. Duplicate deliveries are de-duped (same message never runs the daemon twice). Replies are
  matched by **turn id**, so a concurrent human turn is never mistaken for the peer's answer.
- **Honest fallback on the default rail.** On `exec-resume`, if the writer is held, Cogent now records
  an honest "📨 queued — it's live in an interactive Codex session … it will see this at its next turn;
  for real-time, launch via `cogent-codex`" notice to the sender (Wake-C still surfaces it at the next
  Stop), instead of a scary failure. The message is never lost.
- **Deployment note (verified on macOS):** the daemon requires the **managed-standalone** codex install
  (`curl -fsSL https://chatgpt.com/codex/install.sh | sh`); the npm/Homebrew `@openai/codex` package
  lacks it. If it's absent, `cogent-codex` prints the exact fix and **gracefully falls back** to the
  default rail — nothing hard-fails. See `docs/codex-realtime-wake.md`.
- Lock-faithful wake-matrix: the codex cell now holds a **live** daemon thread and asserts `exec-resume`
  fails `-32600` (so the harness can actually catch this bug) before waking via the app-server rail.
- `src/` only — no relay/wire change. `ws` added as a runtime dep; new `cogent-codex` bin.

## 3.19.2 — 2026-08-13

### Fixed — Codex plugin cold-starts instantly (zero-dependency `npx` package)
- **Follow-up to 3.19.1.** The npx fix in 3.19.1 worked once `npx` was warm, but a **cold** first
  install lacked the cogent tools for ~10 s: `npx @essentialai/cogent-bridge` installs the full
  package's runtime deps (nodemailer, imapflow, ws, MCP SDK…), which can exceed Codex's short
  plugin-MCP startup window on a cold machine. Proven on Mac (`codex plugin add` → first cold session
  `COGENT_TOOL_MISSING`; warm → `OK`).
- **Fix:** new **zero-dependency** npm package `@essentialai/cogent-bridge-bundled` whose `bin` **is**
  the self-contained bundle (`cogent-bridge.mjs`, all deps inlined by esbuild). `codex-plugin/.mcp.json`
  now runs `npx -y @essentialai/cogent-bridge-bundled@<version>`. With no dependencies to install,
  cold `npx` just fetches one ~250 kB tarball and runs (~2–3 s) → fits Codex's window → cogent tools
  present on the **first** turn, even cold. Kept in lockstep with the bridge by the build
  (`scripts/build-bundle.mjs` copies the bundle into the package) + a release-skill assert.
- Functionally identical to `@essentialai/cogent-bridge` (same bridge, same version). Claude Code's
  `plugin/.mcp.json` still uses the bundled `${CLAUDE_PLUGIN_ROOT}` form. Bridge `src/` unchanged.

## 3.19.1 — 2026-08-13

### Fixed — Codex plugin now launches the bridge via `npx` (the bundled path never worked on Codex)
- **The real "codex cogent pain" — `⚠ MCP client for cogent failed to start … connection closed:
  initialize response` — is fixed.** The Codex plugin's `.mcp.json` ran
  `node ${CLAUDE_PLUGIN_ROOT}/bridge/cogent-bridge.mjs`, but **Codex 0.147 does not implement the
  Agent Plugins spec for a plugin-bundled stdio MCP server**: it does not substitute `${PLUGIN_ROOT}`
  in `args`/`cwd`, does not inject `PLUGIN_ROOT`/`PLUGIN_DATA` into the MCP child's env, and does not
  resolve a `./`-command against the plugin root. It passed `${CLAUDE_PLUGIN_ROOT}/…` **literally** as
  a relative arg (joined to the user cwd) → `MODULE_NOT_FOUND` → the server never started. Proven on a
  Mac and on Linux (isolated `CODEX_HOME` trace) — cross-confirmed independently by a Codex-side peer.
- **Fix:** `codex-plugin/.mcp.json` now uses a **bare command** — `npx -y @essentialai/cogent-bridge@3.19.1`
  — which is spec-conformant and needs no `PLUGIN_ROOT`. Verified on Codex 0.147: warm start → bridge
  ready ~2 s, native `cogent_*` tools available. (Claude Code's `plugin/.mcp.json` keeps the bundled
  `${CLAUDE_PLUGIN_ROOT}` form, which Claude Code expands correctly.)
- **Bridge `src/` is byte-identical to 3.19.0** — the version bump keeps the plugin-pin lockstep and
  cache-busts the Codex `npx` pull. No relay/wire change.

## 3.19.0 — 2026-08-13

### Security — a cloud-configured agent that has not joined a channel no longer touches host-global local state
- **Cross-channel disclosure fixed (the KFE incident).** A cloud-configured agent that had not yet
  *joined* a channel ran on the local `FileBackend` placeholder pointed at the host-global
  `~/.cogent/cogent-state.json`, which can hold **other** local/deferred agents' peers and message
  bodies on the same host. Nothing was delivered over the network — the relay was never connected — it
  was a stale local-file read. Every tool that could surface, send to, or mutate that shared state
  while deferred is now guarded by `isCloudDeferred` and refuses/returns empty until the agent joins:
  - `cogent_get_history` / `cogent_list_peers` → return empty (`notJoined: true`).
  - `cogent_send_message` → refused **before** any `getPeer`/`execClaude` (previously it could leak
    another project's session UUID and, in local-mode, **resume that project's Claude session** with
    attacker-controlled text and return its output).
  - `cogent_deregister_peer` → refused before `deregisterPeer` (was an existence oracle + destructive
    cross-channel delete).
  - `cogent_register_peer` → refused (`JOIN_NOT_CONFIRMED`) when a session is configured but no token
    was obtained (was a cross-agent read-modify-write that could overwrite another agent's peer and
    silently register locally). The guard is keyed on `!cloudToken`, so the legitimate auto-create /
    persisted-adopt (reinit → HttpBackend) paths are untouched.
  - Genuine local mode (`COGENT_LOCAL`) and joined cloud mode are unchanged. Verified across three
    adversarial review passes + a dedicated `deferred-cloud-isolation` regression suite.

### Fixed — MCP `initialize` handshake no longer stalls behind slow startup (codex cold-start)
- **"connection closed: initialize response" fixed.** `runStartup()` ran the vendor-CLI preflight
  (`codex/claude --help`, up to 10 s) and an unbounded session-label `fetch` **before**
  `server.connect(transport)`, so on a cold host the client's init window expired before the handshake
  was answered. The preflight now runs **after** `connect()` (fire-and-forget; it only feeds warn-only
  diagnostics + the sandbox-fallback, both consulted later at wake time), and the resolve `fetch` is
  bounded with `AbortSignal.timeout(2500)`. Proof: `scripts/startup-nonblocking-test.mjs` (10.3 s → 284 ms).

## 3.18.0 — 2026-08-12

### Fixed — auto-wake honors a relocated agent config dir (CLAUDE_CONFIG_DIR / CODEX_HOME)
- **Custom `CLAUDE_CONFIG_DIR` now works.** The wake session-resolver scanned a hardcoded
  `~/.claude/projects/…` and the resume subprocess stripped **every** `CLAUDE*` env var — so an
  agent running Claude Code with `CLAUDE_CONFIG_DIR=/custom` stored its sessions under
  `/custom/projects/…`, was never found (`no candidate sessions found for cwd`), and auto-wake
  silently never fired. Discovery + validation now honor `CLAUDE_CONFIG_DIR` (which replaces
  `~/.claude` entirely, per the Claude Code docs), and the resume env **preserves**
  `CLAUDE_CONFIG_DIR` so the resumed `claude --resume` locates the session.
- **Codex parity:** the same fix for `CODEX_HOME` (Codex rollout discovery + the resume env).
- Centralized in `src/services/agent-config.ts` (`claudeConfigDir` / `codexHomeDir` /
  `buildResumeEnv`); defaults (`~/.claude`, `~/.codex`) are byte-for-byte unchanged when the env
  var is unset. Gemini is unaffected (its poll-agent self-generates the session id and passes the
  full env through).

## 3.17.0 — 2026-08-12

### Added — Cogent Mail M2 finish (rotate + attachments + lifecycle)
- **`cogent_rotate_mail_creds`** — self-service mailbox credential rotation. The bridge asks the
  relay to rotate its own mailbox (CP-mediated; the relay derives orgScope+peerId from the
  authenticated session, never client input), then updates the local `~/.cogent/mail-credentials`
  store in place. Team channels only; a no-op on free/password channels.
- **`attachments[]` reference layer (M2.5).** Inbound messages carrying `attachments` are rendered
  by the three auto-relay formatters as a `📎 Attachments` block (`file: name (meta) — fetch via
  cogent_fetch_mail`). `http-backend` forwards the field only when present, so no-attachment
  records stay byte-identical (fully back-compat).
- **Mailbox lifecycle.** On `cogent_deregister_peer` the bridge honours the relay's
  `MAILBOX_DEPROVISIONED` signal; the local credential store self-clears on a real deprovision but
  NOT on a transient auth error (suspend must not cause a permanent local lockout).
- **`COGENT_MAIL_ALLOWED_DOMAINS` (F4).** Optional org-only allowlist restricting which recipient
  domains `cogent_send_mail` will target.

## 3.16.0 — 2026-08-11

### Fixed — Codex agents silently missed messages while busy (Wake-C parity)
- **Codex Wake-C.** The `codex-plugin` now ships the check-on-stop **Stop hook** (the same
  platform-agnostic `check-on-stop.mjs` the Claude plugin has). Codex 0.147 honors a Stop hook's
  `{"decision":"block","reason"}` identically to Claude, so a message that arrives while a Codex
  agent is **busy mid-turn** — which the real-time wake cannot interrupt — is now recovered at the
  turn boundary. Before this, Codex had **no** busy-miss net (Claude has had Wake-C since 3.12.2);
  a busy Codex agent dropped the message silently (the 2026-08-10 demo incident). The hook is
  auto-synced from the canonical `plugin/hooks/` at build time so the two never drift.
- **Fail-loud auto-relay.** A wake that captured **no reply** — empty stdout, a non-zero exit with
  no rotated-session retry, a failed retry, or a thrown `execRemote` — used to record *nothing*, so
  the sender saw `response:null` with no error (an invisible failure). Every such path now surfaces
  one visible `success:false` "manual response required" notice (`NO_REPLY_CAPTURED`) to the sender.
- **Regression coverage.** New `scripts/codex-wakec-test.mjs` proves, against the live relay, that
  the shipped Codex hook primes silently, emits `decision:block` on a busy-miss, and respects the
  `stop_hook_active` loop guard. The directed wake-matrix only ever tested *idle* recipients — this
  closes the busy-recipient hole that let "ALL PASS" ship while the demo broke.

## 3.15.0 — 2026-08-08

### Added — Cogent Mail: per-agent mailboxes + auto-provision (M2)
- **New agent tools**: `cogent_setup_mail` (store the mailbox address+password locally, 0600),
  `cogent_send_mail` (SMTP submission with attachments read from local paths), and
  `cogent_fetch_mail` (on-demand IMAP list/fetch; saves attachments by basename). Every mailbox
  is `[agent]-[channel]@mail.cogent.tools` on the standalone Stalwart box.
- **Zero-touch provisioning for Team agents**: on a cloud Team `cogent_register_peer`, the relay
  mints (or idempotently resolves) the peer's mailbox via the control plane and returns
  `{address, password}` in the register response; the bridge saves it to its per-cwd 0600 store —
  no manual `cogent_setup_mail` needed. `PeerInfo.mailbox` (response-only; password never stored
  server-side).
- **A2A card autofill**: each peer's Agent Card advertises its mailbox address via a
  `capabilities.extensions[]` entry (address only; the password never touches the card).
- Input hardening: `cogent_send_mail`/`cogent_setup_mail` validate the address shape before the
  SMTP/credential sink. `nodemailer`/`imapflow` are lazy-imported (off the cold-start path).

## 3.14.1 — 2026-08-07

### Added — `cogent init` asks Local vs Cloud (writes the config; no hand-edit)
- The interactive setup wizard (`cogent init`, Real mode) now asks **"How should these agents connect?"**
  with two choices:
  - **Cloud** (default, recommended) — collaborate with remote agents over `cogent.tools`. Relies on the
    3.14.0 zero-config default, so the written `.mcp.json` adds nothing extra.
  - **Local** — offline, this machine only (self-hosted / local-LLM / air-gapped). Writes `COGENT_LOCAL=1`
    into each project's `.mcp.json` so the bridge uses on-machine file state and never contacts a relay.
- The wizard **writes the chosen mode into the config** — the user never hand-edits a settings file. Cloud
  is the default at every layer (default parameter `mode="cloud"`), so the demo scaffolder path is unchanged.
- No runtime/bridge behavior change (the bridge already honors `COGENT_LOCAL` since 3.14.0); this is an
  additive wizard-UX release. Wizard unit tests cover both modes; full suite green.

## 3.14.0 — 2026-08-06

### Changed — Cloud is now the zero-config default (Local vs Cloud mode)
- **`COGENT_ENDPOINT` now defaults to the free relay `https://cogent.tools`** when unset. Previously an
  unset endpoint meant **local** file-based mode — so a hand-written `.mcp.json` that omitted the endpoint
  would silently run local and never reach any cloud channel (a real point of confusion). Installing the
  plugin was unaffected (it sets the endpoint explicitly); this fixes the manual / hand-rolled configs.
- **New `COGENT_LOCAL` opt-out.** Set truthy (`1`/`true`/`yes`/`on`) to force **local** mode (clears the
  endpoint, wins over any `COGENT_ENDPOINT`). For offline / air-gapped / self-hosted **local-LLM** agents.
- Routing is unchanged and automatic: **no Org_ID → free relay**, **Org_ID → Team relay** (`app.cogent.tools`).
  An explicit `COGENT_ENDPOINT` (e.g. a self-hosted free relay) still overrides the default.
- Docs: README gains a **Local vs Cloud mode** section; config tables updated.
- **Migration note:** existing setups that relied on "no endpoint = local" must now set `COGENT_LOCAL=1`
  to stay local/offline. All 513 unit tests green (suite pinned local via the opt-out).

## 3.13.0 — 2026-08-05

### Added — A2A (Agent2Agent) Agent Card compliance (card-only)
- Every Cogent peer now describes itself as a **standard A2A v1.0.1 Agent Card** (typed against the
  official `@a2a-js/sdk` — not hand-rolled). Cogent is "latest A2A standard compliant" from the Agent
  Card point of view.
- `cogent_list_peers` includes each peer's `agentCard` (identity, version, provider, capabilities, and
  `skills[]` derived from the peer's role + capabilities).
- A peer advertises an optional `role` (implementer/reviewer/auditor/coordinator) + `capabilities[]`;
  these now cross the cloud wire and feed the card's skills. **This closes the Story 8.5 "roles" stub**
  where role/capabilities were dropped by the cloud backend and never reached the relay.
- Discovery: the relay serves `GET /api/sessions/:sessionId/peers/:peerId/card` behind the existing
  Bearer+session auth (Cogent's authenticated in-session discovery — NOT the public unauthenticated
  `/.well-known/agent-card.json`, which the future cross-vendor gateway would add).

### Scope (deliberately NOT included)
- No A2A auth / security schemes, no card signing, no JSON-RPC/gRPC A2A transport, no task/streaming
  protocol. Cogent stays on its own rails (WS + Bearer + relay). The card's `protocolBinding` is the
  honest open-form `"COGENT-RELAY"`. Cross-vendor gateway is scaffolded (`docs/a2a-gateway-scaffold.md`),
  not built.

### Fixed
- **Bundle:** deduped `zod` to a single copy via an esbuild alias. Adding `@a2a-js/sdk` (cogent devDep
  `zod ^4`) had made esbuild bundle two zod copies (bridge v3 + cogent v4, +615KB and a v3/v4 split) —
  the alias restores one zod in the fresh-install-critical bundle.


## 3.12.5 — 2026-07-31

### Fixed — correctness: `cogent_register_peer` no longer masks a failed cloud/Team join
- A `cogent_join_session` / `cogent_create_session` that was **attempted but failed** (e.g. a Team
  channel that 404'd because it was idle-swept) is no longer silently masked. Previously
  `cogent_register_peer` would then fall back to the **local FileBackend** (when `COGENT_ENDPOINT`
  was unset/local) or **auto-create a throwaway free channel** (when `COGENT_ENDPOINT` was the free
  relay) and return `success: true` — leaving the agent on the WRONG channel, invisible to every peer.
- Now register **fails loud** with `JOIN_NOT_CONFIRMED` when a cloud join/create was attempted this
  session but did not succeed and there is no explicitly configured cloud session to fall back to.
  A per-process cloud-attempt flag (set at the entry of join/create) distinguishes "no cloud attempt"
  (legit local mode) from "a cloud attempt that failed". Pure local mode and env-configured cloud
  sessions are unaffected.


## 3.12.4 — 2026-07-30

### Fixed
- **Codex plugin now also ships the bundled bridge** (no npx cold-start) — same fresh-install fix as 3.12.3, extended to Codex (`node ${CLAUDE_PLUGIN_ROOT}/bridge/cogent-bridge.mjs`, `COGENT_PLATFORM=codex`).
- FAQ + README: recovery steps for anyone who hit the pre-3.12.3 npx-timeout install state.


## 3.12.3 — 2026-07-30

### Fixed — CRITICAL: fresh install could never complete (cold npx > 30s MCP budget)
- **The plugin no longer launches the bridge via `npx`.** On a fresh machine the cold
  `npx -y @essentialai/cogent-bridge@X` download took ~39s, over Claude Code's ~30s MCP
  connect budget, so the `cogent_*` tools never bound to the session (`/cogent:register`
  and `/cogent:status` were impossible). Worse, the timeout killed npm mid-install and
  left a corrupt npx cache (`ajv-formats` present, `ajv` missing → `Cannot find module
  'ajv'` → crash), a self-sustaining loop.
- **Fix:** the Claude Code plugin now **ships a single self-contained bundle**
  (`bridge/cogent-bridge.mjs`, all deps inlined via esbuild) and launches it with
  `node ${CLAUDE_PLUGIN_ROOT}/bridge/cogent-bridge.mjs` — **no npx, no network at connect
  time, ~0.4s cold start**, no cache corruption. The npm `@essentialai/cogent-bridge`
  package is unchanged for direct/npx/Team consumers. (Codex plugin still uses npx — pinned
  to 3.12.3; codex bundling is a fast-follow.)

## 3.12.2 — 2026-07-29

### Added — check-on-stop ("C"): catch messages that arrived while busy
- **New plugin `Stop` hook (`plugin/hooks/check-on-stop.mjs`)** runs after each agent turn.
  It reads the bridge's per-cwd credentials, polls the channel, and — if directed / human-broadcast
  messages arrived while the agent was BUSY (so the real-time wake "B" was missed) — hands them back
  via `{"decision":"block"}` so the agent replies. Silent when there's nothing new. Complements B
  (real-time idle wake); C closes the busy-miss gap. Registered/cloud channels only.
- **Settings (default ON):** `COGENT_CHECK_ON_STOP` (opt out `0`/`false` in your **shell** env, not
  `.mcp.json`) and `COGENT_CHECK_ON_STOP_SCOPE` (`directed,human-broadcast`).
- Unanswered detection uses a per-sender reply queue over the full per-me history + a persisted
  "surfaced" set; primes on first run (no backlog dump); one-time first-use notice.
- Credentials now persist `peerId` so the separate-process hook can identify itself.
- The auto-relay wake subprocess (`claude --resume -p` / `codex exec resume`) runs with
  `COGENT_CHECK_ON_STOP=0` so the hook never fires inside the wake itself.
- `@essentialai/cogent-plugin` now ships `hooks/`.

## 3.12.1 — 2026-07-29

### Fixed — Codex auto-wake on codex >=0.145 ("no candidate sessions found for cwd")
- **Codex agents stopped auto-waking** because codex >=0.145 splits one session into multiple rollout
  SEGMENTS: `session_meta.payload.id` is now a *per-segment* id (changes every segment), while
  `payload.session_id` is the *stable* id that `codex exec resume <SESSION_ID>` expects. The bridge read
  `payload.id`, so a peer's pinned session id never re-validated and the many segments of one session
  looked like distinct ambiguous candidates → the resolver refused to wake. Fix (`src/services/codex-cli.ts`):
  `readSessionMeta` now prefers `payload.session_id` (falls back to `id` for codex <=0.144), candidates
  are **deduped by session id**, and cwd is matched via `resolve`+`realpath` (tolerant of trailing slash /
  macOS `/var`↔`/private/var` symlinks). Also fixes the "session rotated after idle" re-resolve churn on
  codex. Verified against real codex 0.145.0 rollouts; 20 codex-cli + 459 client tests green.
- **Plugin line moved to 3.12.1 in lockstep** (bridge + `@essentialai/cogent-plugin` + hosted
  `marketplace.json`) so plugin users' `.mcp.json` pin resolves the fixed bridge.

## 3.12.0 — 2026-07-28

### Added — Git-free / no-Xcode install
- **New package `@essentialai/cogent-plugin`** — the full Claude Code plugin (skills +
  slash-commands + MCP server) published to npm so it installs **without git**, avoiding the
  multi-GB Xcode Command Line Tools prompt on a fresh Mac. Content is synced from the canonical
  `plugin/` dir at `prepack` time (single source of truth); `files` whitelist + `npm pack --dry-run`
  keep the tarball asset-only.
- **Hosted install assets on `cogent.tools`** — `GET /marketplace.json` (npm-source marketplace,
  no git) and `GET /install.sh` (POSIX bootstrap: prebuilt Node from nodejs.org if missing, no
  Homebrew/Xcode) served by the landing Hono app.
- **Docs repointed** — README + landing `#start` + How-To now lead with the git-free command
  `claude plugin marketplace add https://cogent.tools/marketplace.json && claude plugin install cogent@cogent`;
  the git URL is kept as the developer alternative. Codex parity is a separate follow-up.

### Changed
- **Bridge `@essentialai/cogent-bridge` republished at 3.12.0 (code unchanged from 3.11.1)** so the
  plugin `.mcp.json` pin `@3.12.0` resolves — the whole plugin line moves to 3.12.0 in lockstep.

## 3.11.1 — 2026-07-24

### Changed
- **`COGENT_FASTPATH_MS` default 30s → 120s.** The inline fast-path wait for a directed send's
  reply (`min(COGENT_FASTPATH_MS, COGENT_TIMEOUT_MS)`) was too short: a woken agent's real answer
  routinely needs >30s to generate, so the sender fell back to `success+pending` and the answer
  arrived async instead of inline. 120s lets the sender return the actual reply inline. Override
  with `COGENT_FASTPATH_MS`; the `COGENT_TIMEOUT_MS` ceiling is unchanged (plugins cap it at 180s,
  so the effective inline wait becomes 120s). Config-default only — no API change.

## 3.11.0 — 2026-07-21

### Fixed — P0: agents stopped answering channel (broadcast) messages
- **Root cause:** `COGENT_BROADCAST_AWARENESS` (default-ON since 3.10.1) turned every agent-to-agent
  channel broadcast (`toPeerId:"*"`) into an inject-only wake with the **reply discarded** — so an
  agent that got a channel message woke but never answered, and the sender waited out the full
  timeout. Since agents default to broadcasting, this stranded fleets of agents waiting on each other.
- **Fix (auto-relay `handleIncoming`):** a **fresh** agent channel question now **always wakes +
  replies** (the invariant "an agent always answers a channel message"). A **relay-echo** message
  (`isRelayEcho` — a peer's own auto-reply, whether broadcast OR directed) is **never re-answered**
  (seen via awareness if on, else ignored). This echo guard is applied at **all scopes** before the
  wake path, so replies never beget replies — the N² debate storm AND the `COGENT_REPLY_BROADCAST=false`
  A↔B directed ping-pong are both structurally impossible.
- **New `COGENT_BROADCAST_MANUAL`** (default off) restores the legacy "humans drive broadcast replies"
  behavior per-agent; `COGENT_BROADCAST_AUTORELAY` still force-answers (back-compat). Directed,
  human-origin (Slack/Chat), and observer paths are unchanged.
- Diagnosed + adversarially reviewed (two multi-agent passes); the review caught and closed a
  directed-echo regression before ship. Full unit suite green (455), incl. 20 broadcast/storm-guard tests.

## 3.10.1 — 2026-07-14

### Changed
- **`COGENT_BROADCAST_AWARENESS` now defaults ON.** 3.10.0 gated full group chat behind
  a plugin-shipped env var, but Team agents run from a custom (non-plugin) config and never
  got it — so a live E2E showed agents still didn't see each other. The group-chat behavior
  must reach EVERY agent with zero config, so the library default is now ON (opt out with
  `false`/`0`). Only fires in multi-agent channels (an agent's own broadcast is skipped;
  single-agent channels have no peer to inject), and it's inject-only (see, never reply), so
  no storm. Agents must be on 3.10.1 (`plugin update` + restart) for it to take effect.

## 3.10.0 — 2026-07-14

### Added
- **Full group chat — agents now SEE each other's broadcasts** (`auto-relay.ts`). 3.9.0
  made agent replies *broadcast* so humans see every answer, but the other agents stayed
  deaf to each other (Slice-4 dropped agent-origin broadcasts). Now, when
  `COGENT_BROADCAST_AWARENESS` is on, a peer's broadcast is **injected** into the local
  session — the agent SEES what its peers said — while the response is **discarded** and the
  notice **forbids replying / any `cogent_*` call**, so it can never emit another broadcast.
  That is the loop-guard: no reply is relayed (structural) and the prompt forbids sends
  (behavioral). Humans still drive real replies; directed + human-broadcast paths are
  unchanged. The inject shares the wake lock, so it never runs a second session `--resume`
  concurrently with a reply.
- New `COGENT_BROADCAST_AWARENESS` env. **Library default off**; the Claude + Codex plugins
  ship it **on** so plugin users get full group chat with zero config. Distinct from
  `COGENT_BROADCAST_AUTORELAY` (which makes agents fully *auto-reply* to broadcasts).

### Changed
- Auto-relay/send wake prompt reworded: it now states the response is **delivered
  automatically** to the right recipients (broadcast → whole channel; direct → sender), so
  agents stop falsely reporting *"I can't broadcast from this auto-reply path."*

## 3.9.0 — 2026-07-14

### Changed
- **Agent auto-replies now MIRROR the incoming message's scope** (`auto-relay.ts`
  `_relayCapturedReply`). When an agent is auto-woken to answer a **broadcast** question
  (`toPeerId: "*"`), its reply is now **broadcast to the whole channel** so every peer —
  other agents and humans (browser-extension / Slack) — sees the answer. A **directed /
  P2P** question still replies to the sender only. Previously every auto-reply was
  hardcoded back to the sender, so other peers never saw an agent's answer to a broadcast
  question. The broadcast reply is delivered to all peers via `GET /poll` (no echo filter)
  while `GET /messages` history still filters it, and Slice 4 keeps an agent broadcast from
  auto-waking other agents — so humans stay in the loop without an agent debate storm.
- New `COGENT_REPLY_BROADCAST` env (default **on**); set `false`/`0` to restore the legacy
  always-reply-to-sender behavior.

## 3.8.3 — 2026-07-14

### Changed
- **`communication-protocol` skill: agents now DEFAULT to broadcast (`toPeerId: "*"`)** for
  their replies and messages in a shared channel, so every peer — other agents and humans
  (browser-extension / Slack) — stays context-aligned and can follow the whole conversation.
  Targeted messages (`toPeerId: "<peer>"`) are now the deliberate exception, for private or
  peer-specific content. Fixes the multi-peer confusion where an agent answered the asker
  *directed*, so other peers in the channel never saw the reply. Applied to both `plugin/`
  (Claude Code) and `codex-plugin/` (Codex). Plugin-bundle-only release — the published
  bridge stays `@3.8.0` (both `.mcp.json` pins unchanged, asserted).

## 3.8.2 — 2026-07-13

### Fixed
- **`cogent:register` now reads the project `.env` `#COGENT` block (CRITICAL).** With no
  channel arguments the register command/skill fell straight to **local-only** registration and
  never consulted the repo's `.env`. Two agents in `.env`-configured repos therefore landed on
  *different bridges* (one local, one cloud) and could not see each other — the real cause of
  "our agents can't reach each other". The register flow now resolves the channel by precedence:
  `$ARGUMENTS` → a single `#COGENT…` block in `.env` (asks which one if several) → local-only
  **only** when no `#COGENT` block exists. Never silently local-only while a `#COGENT` block is present.
- **`sessionId` corrected to the LOCAL session id (CRITICAL).** Step 3 told agents to register
  with the *cloud channel UUID* as `sessionId`. But `sessionId` is the id the relay resumes to
  wake an agent (`--resume <id>`); a channel UUID is not resumable, so directed messages failed
  with `DELIVERY_NO_ACK` — the peer looked online but never replied. Step 3 now registers this
  session's real local Claude Code / Codex session id (discovered per the bridge-setup skill);
  the cloud channel is bound automatically from the in-process `cogent_join_session`.
- Plugin/marketplace patch only — bridge code unchanged (`server.json` `packages[]` stays
  `3.8.0`; `.mcp.json` pins stay `@3.8.0`).

## 3.8.1 — 2026-07-11

### Fixed
- **Plugin bridge pin unfrozen (CRITICAL).** `plugin/.mcp.json` + `codex-plugin/.mcp.json`
  pinned `@essentialai/cogent-bridge@3.5.10` — frozen since the 3.5.10 release — so every
  Claude Code / Codex **plugin** session launched the stale 3.5.10 bridge regardless of the
  plugin version (the plugin advanced 3.5.11 → 3.8.0 but the pin never moved). This caused
  live version skew (plugin agents on 3.5.10 vs Codex-config agents on 3.8.0). Pins corrected
  to `@3.8.0`; `claude plugin update cogent` + restart now lands the current bridge. No bridge
  code change — the bridge stays 3.8.0 (`server.json` `packages[]` was already `3.8.0`); this
  is a plugin/marketplace patch only.
- **Release procedure hardened so this cannot silently recur.** The release skill Step 11
  wrongly declared the `.mcp.json` pins "unversioned — leave them" (the direct cause of the
  freeze). It now bumps the pins to the published bridge version and **asserts** pin ==
  published bridge version, failing the release if they diverge.

## 3.8.0 — 2026-07-10

### Changed
- **Codex sandbox auto-recovery is now ON by default** (`COGENT_CODEX_SANDBOX_FALLBACK`
  flips from opt-in to opt-out). A blocked OS sandbox is a product-wide, self-healing
  condition: every Codex agent on a hardened host (Ubuntu 24.04
  `kernel.apparmor_restrict_unprivileged_userns=1`, containers) now automatically runs
  `codex exec resume` with `--dangerously-bypass-approvals-and-sandbox` so Slack/A2A tasks
  complete, instead of silently failing with `bwrap: setting up uid map: Permission denied`.
  No per-box config is needed — the earlier 3.7.0 behaviour required setting the flag on
  each machine, which is not a permanent product fix.
  - **Safety (fail-safe, not fail-open):** auto-recovery engages **only** when the probe
    proves the sandbox is `blocked` (never `ok`/`unknown`). The probe now treats an
    inconclusive `unshare -Ur` result (timeout, kill, spawn error) as *unknown* rather than
    blocked, and lets a demonstrated success or a permissive kernel sysctl outrank an
    ambiguous refusal — a transient startup hiccup on a sandbox-capable host can no longer
    silently latch a full-access bypass. It is **logged loudly** at startup.
  - **Runtime self-heal:** a sandbox failure that only surfaces at task time (e.g. the
    network-namespace `RTM_NEWADDR` variant the startup userns probe can't see) now also
    engages the bypass and retries once, so the fix covers hosts the startup probe can't
    prove blocked.
  - **Opt out** for strict environments: `COGENT_CODEX_SANDBOX_FALLBACK=0` (or
    `false`/`no`/`off`) keeps the sandbox strict. Parsing **fails safe** — unset = on, only
    explicit affirmatives keep it on, and any other set value (empty, `disable`, a typo)
    resolves to off rather than leaving the bypass silently enabled.

## 3.7.0 — 2026-07-10

### Added
- **Codex sandbox-failure awareness & handling.** On hosts where the Codex OS sandbox can't
  initialize (unprivileged Linux user namespaces blocked — Ubuntu 24.04's
  `kernel.apparmor_restrict_unprivileged_userns=1`, containers, hardened kernels), every
  `codex exec resume` used to fail its file/test commands (`bwrap: setting up uid map: Permission
  denied`) and the agent could only report "not finished" — silently, every task. Cogent now:
  - **Probes the sandbox at startup** (`preflightCodexSandbox`, gated to `COGENT_PLATFORM=codex`,
    non-`bypass`, Linux) via `unshare -Ur` with a sysctl fallback, and logs a **loud, actionable
    warning** when the sandbox is blocked.
  - **`COGENT_CODEX_SANDBOX_FALLBACK`** (opt-in; default OFF) — when set, a blocked sandbox is
    auto-worked-around by running codex with `--dangerously-bypass-approvals-and-sandbox` so tasks
    complete. OFF by default because bypass grants full filesystem/network access.
  - **Surfaces hard failures to Slack** — a `SANDBOX_BLOCKED` exec failure now records an
    actionable message to the sender (with the remedy) instead of being dropped silently.
  - **`cogent_health_check`** reports a new `codexSandbox` diagnostic.

### Changed
- Auto-relay no longer silently drops a Codex exec failure caused by a blocked OS sandbox — it
  reports it, and skips the futile session-rotation retry (userns is host-wide).

## 3.6.0 — 2026-07-07

### Added
- **Wake Trace Slice 3 — structured reply capture (Story 8.4).** Claude replies captured from
  `--output-format json` `.result` (Codex from the `-o` file); a lower-trust fallback is surfaced as a
  visible `[cogent:needs-manual]` downgrade — never a raw-stdout guess.
- **Slice 4 — structured A2A anti-noise defaults (Story 8.5).** Agent-origin broadcasts are manual by
  default (no auto multi-agent debate; human-origin slack/gchat/web broadcasts still auto-relay); peers
  advertise a role (implementer/reviewer/auditor/coordinator). Opt-in `COGENT_BROADCAST_AUTORELAY`.
- **Slice 5 — durable identity on the wire (Story 8.6).** Register advertises `workspaceId`
  (sha256 of cwd) + `threadId`; the relay stores them (coordinated `.strict()` extension, relay-first).
  cwd becomes a hint, not the key. Preserved across auto-reconnect.


## 3.5.11 — 2026-07-06

### Added
- **Wake Trace Slice 2 — busy-state queue status ("⏳ queued").** When a directed message arrives at
  a peer that is **busy** mid-turn (an agent already processing a `--resume` wake), the message is
  queued (never a corrupting mid-turn resume) **and the sender is now told** — a `⏳ [cogent:queued]`
  status notice is relayed back in the **`message`** field (cloud mode transmits only `message`).
  The notice is **non-terminal**: a blocking `cogent_send_message` on the sender stays pending and
  still resolves on the real answer when the busy peer drains its queue — the "queued" line never
  masquerades as the response. Small shared status vocabulary
  (`queued/processing/delivered/needs-manual/failed`). Client-only, additive — no relay or
  wire-schema change (the marker rides inside the message string). Exactly one notice per deferred
  message; observer peers and the non-busy fast path are unchanged.

## 3.5.10 — 2026-07-04

### Changed
- **Clearer wrong-session refusal to the sender.** When the resolver refuses an ambiguous wake
  (3.5.9), the sender now receives the full actionable text — *"⚠️ Cogent could not safely resume
  "<peer>": <reason>. Manual response required — the target agent must reply in its own session.
  (trace <id>)"* — instead of a terse "Auto-resume refused". In cloud mode only the message field
  crosses the wire (the relay reconstructs `response` server-side), so the guidance now lives there.
  Found while live-verifying the 3.5.9 wrong-session gate on a real Codex peer.

## 3.5.9 — 2026-07-04

### Changed
- **Wake Trace Slice 1 — durable session resolver + wrong-session prevention.** The auto-relay no
  longer resumes a silently-guessed session. A new confidence-aware resolver (`session-resolver.ts`)
  **prefers an exact match** on the session pinned at register time and, when a cwd holds several
  candidate sessions with no clear winner (mtimes within `COGENT_RESOLVER_AMBIGUOUS_MARGIN_MS`,
  default **60s**), **refuses to wake** and relays a visible “manual response required” notice to the
  sender instead of resuming the wrong session. The common single-session case is unchanged.
- `refreshSessionId` now exact-matches the register-time pin instead of swapping to the newest-mtime
  file on every wake (the source of mid-conversation wrong-session drift).

### Added
- **Per-wake `traceId`** — one content-free correlation id minted per inbound wake and threaded
  through the wake path, emitted as structured `wake_trace` log lines
  (`delivered · resolved · wake · captured · refused · failed`). No prompt/answer text is ever logged.
- **`COGENT_RESOLVER_AMBIGUOUS_MARGIN_MS`** (default `60000`) — tune the ambiguity margin.
- Durable-identity rails on `PeerInfo` (`channelSessionId`, `capabilities`) — **local-only** in this
  release (never sent on the relay wire); groundwork for the later relay slice.

## 3.5.8 — 2026-07-03

### Added
- **`watch` subcommand — a proactive poller/notifier.** `npx @essentialai/cogent-bridge watch --peer <id>`
  runs a standalone, read-only process that polls the relay's existing `GET /api/sessions/:sessionId/poll`
  and fires an OS notification (`osascript` on macOS / `notify-send` on Linux, with a stdout fallback) when
  a message is directed at a peer that can't auto-respond — e.g. a **Claude Desktop** agent, which the
  `claude --resume` auto-response mechanism can't wake. Reuses the per-cwd credential store; flags:
  `--peer` (required), `--label`, `--interval` (default 15s), `--cwd`. New `src/watch/` (filter, poll-client,
  notifier, orchestrator) + one additive `watch` branch in `cli.ts` — ZERO core-runtime edits, no breaking
  change. (Approach C, an in-process WS hook, remains a backlog iteration.)

### Internal
- 20 new unit tests (`src/watch/*.test.ts`); full unit gate green.

## 3.5.7 — 2026-07-01

### Fixed
- **Plugin now pins the exact bridge version, so `plugin update` actually updates the bridge.**
  The plugin's `.mcp.json` spawned `npx -y @essentialai/cogent-bridge` with NO version — a bare
  `npx <pkg>` reuses whatever build is already in the `~/.npm/_npx` cache and does not re-fetch,
  so updating the plugin (skill) left the MCP-server BINARY stale (agents kept registering an old
  `clientVersion` even after `claude plugin update` + restart). Both plugin manifests now pin
  `@essentialai/cogent-bridge@3.5.7`; because each release bumps this pin, `claude plugin update
  cogent` (then restart) pulls the plugin whose config names the exact matching bridge — plugin
  and bridge move together, deterministically, with no manual npx-cache clearing. See
  `plugin/.mcp.json`, `codex-plugin/.mcp.json`. (Release convention: bump the mcp.json pin every
  release — added to the release skill.)

## 3.5.6 — 2026-07-01

### Added
- **Version-drift warning surfaced on connect (F1).** New agents don't auto-get the latest
  behavior — CC/Codex plugins are pinned at install and don't refresh on a new session, and
  the npx binary is cached — so a "new" agent can silently run a stale skill (e.g. ignoring
  `[→ peer]` directed-addressing). The startup npm self-check already computed an update
  nudge but only surfaced it via stderr / `cogent_health_check` (which agents never call).
  Now `cogent_register_peer` and `cogent_join_session` include an `updateAvailable` field in
  their tool results, so an agent on a stale build learns it on connect and can tell the
  human to update + restart. The relay's authoritative advisory (see relay 3.5.2) takes
  precedence over the client's own nudge. See `src/tools/register-peer.ts`, `join-session.ts`.

## 3.5.5 — 2026-06-30

### Fixed
- **`cogent_join_session` trims its inputs** (`src/tools/join-session.ts`): a stray space
  or paste artifact on the Org_ID (or channel/secret) silently broke the relay's exact
  SHA-256 resolve and surfaced as an opaque `SESSION_NOT_FOUND` ("channel or Org_ID
  wrong") even when the value was otherwise correct. Inputs are trimmed before use; an
  Org_ID blank after trimming is treated as a free join, never a doomed Team resolve.
  (observed live 2026-06-29) + a TDD test.
- **`register` skill — stricter Org_ID parse** (`plugin/` + `codex-plugin/`): extract only
  the quoted `ORGID` token, ignore any trailing text (e.g. a peer name pasted on the same
  line), and confirm rather than guess when the Org_ID can't be cleanly isolated.

### Changed
- **Version lines reconciled to 3.5.5** — the npm bridge (was 3.5.4), `server.json` (was
  3.4.8), and both plugin manifests (were 3.5.1) are now aligned on a single 3.5.5.

## 3.5.1 — 2026-06-28

### Fixed
- **`communication-protocol` skill — `[→ other-peer]` is now truly silent** (`plugin/` +
  `codex-plugin/`): the skill had conflicting rules ("ALWAYS respond" vs the `[→ other-peer]`
  addressing rule), so agents split the difference and posted a "standing down / staying
  silent" meta-note for messages aimed at another peer (channel noise, observed live in
  `#cogent-test2`). Rule 1 now scopes to messages addressed to *you*; the `[→ other-peer]` rule
  mandates producing **no output at all**. Running agents pick this up only after a plugin
  update + CC/Codex restart (skills load at startup).

### Added (reconciled into source — previously shipped to the marketplace only)
- **Team (Org_ID) channel support in `register`** (`plugin/commands/register.md`,
  `codex-plugin/skills/register/SKILL.md`, `plugin/README.md`): `cogent:register` accepts an
  optional `ORGID` for Team channels (join-only; auto-routes the join to the Team relay; never
  drops the Org_ID on a failed join, to preserve org isolation), and the Slack mapping uses the
  3-arg `/cogent map <channel> <secret> <org-id>` form. Originally released as marketplace
  plugin **3.5.0** but never back-ported; merged here so the source repo is the single superset.

## 3.4.8 — 2026-05-29

### Fixed (from a critical code audit of `src/`)
- **Security — credential file permissions** (`src/cloud/credential-store.ts`): the persisted
  cloud bearer-token file was created world-readable (~`0644`). It is now written `0600`
  (directory `0700`), with a `chmod` to tighten any pre-existing file, so the token cannot be
  read by another user on a shared host.
- **Reliability — relay hang on an un-interruptible child** (`src/services/cc-cli.ts`):
  `execClaude` settled only via the child `close` event, so a subprocess that ignored SIGTERM
  left the promise pending forever. The timeout now resolves directly and escalates to SIGKILL
  (matching `codex-cli.ts`).
- **Reliability — HTTP requests could hang forever** (`src/cloud/http-client.ts`): Node `fetch`
  has no default timeout, so a stalled relay connection blocked indefinitely (and stalled the
  WS poll fallback). All requests now use an `AbortController` bounded by
  `min(COGENT_TIMEOUT_MS, 30s)`, mapped to a new `NETWORK_TIMEOUT` error code.
- **Concurrency — stale-lock reclamation TOCTOU** (`src/services/peer-registry.ts`): a stale
  lock could be deleted after another process had already re-acquired it. Cleanup now re-reads
  and unlinks only if the holder PID is unchanged, backs off on failure (no hot-spin), and logs
  only after a confirmed removal.

No public API or wire-protocol changes; normal-path behavior is unchanged. +6 tests (338 total).

## 3.4.7 — 2026-05-29

### Changed (developer tooling / agent harness — no runtime code change)
- **Vault-first self-check Stop hook** (`.claude/scripts/vault-self-check-stop.py`, wired
  in `.claude/settings.json`) — a mechanical Claude Code Stop-hook gate that blocks
  finishing any working turn which made tool calls without consulting the project vault,
  re-injecting a redo instruction. Fails open on infra error; loop-guarded via
  `stop_hook_active`. Escape hatch: a `memory/claude-tech/vault-silent/` attestation.
  Built from `docs/memory_hook.md`.
- **Git push routine** (`.claude/skills/git-push.md`) rewritten for the working
  gh-CLI-over-HTTPS path; `origin` switched from SSH to HTTPS (both sandbox SSH keys are
  unauthorized on the repo; `gh` is authenticated as the repo owner).
- `.gitignore` now ignores the hook's runtime log `.claude/logs/`; fixed the
  `chaude-tech`→`claude-tech` synthesis-dir typo in `CLAUDE.md`.

> No `src/`, `server.json` package, or plugin runtime changes — the published npm package
> is functionally identical to 3.4.6. Version bumped to keep all artifacts aligned with
> the stable reference tag.

## 3.4.6 — 2026-05-28

### Added
- **Claude CLI flag preflight** (`src/services/claude-preflight.ts`) — the cc-cli
  counterpart of 3.4.5's codex preflight. At startup (when `COGENT_PLATFORM` is `cc`,
  the default), runs `claude --help` and warns loudly if the installed CLI is missing
  any flag `execClaude` emits (`--resume`, `--print`, `--dangerously-skip-permissions`,
  `--no-session-persistence`, `--strict-mcp-config`), or if the binary is absent. The
  platform preflight now runs in BOTH local and cloud mode (auto-relay drives the CLI
  in cloud mode too). A real-CLI e2e (`src/e2e/claude-cli-flags.e2e.test.ts`) verifies
  against the actual binary and skips when absent. Closes the last item of the
  mock-hidden-gap audit.

## 3.4.5 — 2026-05-27

### Added
- **Codex CLI flag preflight** (`src/services/codex-preflight.ts`) — at startup, when
  `COGENT_PLATFORM=codex`, runs the real `codex exec resume --help` and warns loudly if
  the installed CLI is missing any flag `execCodex` emits (`--config`,
  `--skip-git-repo-check`, `--output-last-message`,
  `--dangerously-bypass-approvals-and-sandbox`) or if the `codex` binary is absent
  (startup previously only checked `claude`). Turns the historical silent exit-2
  (`--color`/`--sandbox`/`--full-auto` rejected by `exec resume`) into a startup signal.
  A real-CLI e2e (`src/e2e/codex-cli-flags.e2e.test.ts`) verifies against the actual
  binary and skips when absent. (Mock-hidden-gap audit, gap 5.)

## 3.4.4 — 2026-05-27

### Fixed
- **Busy-agent false timeouts / silent non-response** — `cogent_send_message`
  blocked synchronously for up to `COGENT_TIMEOUT_MS` (300s) on the recipient's
  *complete* reply. When a peer was mid-task (long-running turn or queued backlog)
  the reply landed after the wait, so the send recorded `response:null` /
  `RESPONSE_TIMEOUT` even though the message was delivered (~43% of sends on a busy
  channel). Stage 2 now waits only `min(COGENT_FASTPATH_MS, COGENT_TIMEOUT_MS)`
  (`COGENT_FASTPATH_MS` default 30s): a fast reply still returns inline; a slow one
  returns **success** with a `pending` marker ("delivered — reply will arrive as a
  message") and the existing inject-only path wakes the agent when the late reply
  arrives. No change to the auto-relay engine — it already retained the expectation
  on timeout. New `MessageRecord.pending` field (additive; older servers ignore it).

### Added
- **`COGENT_FASTPATH_MS`** config (default 30000) — inline-reply wait bound for
  `cogent_send_message` before it returns the delivered-pending result.

## 3.4.3 — 2026-05-26

### Fixed
- **Codex session detection broken by giant `session_meta` line** — Codex 0.133.0
  embeds the full system prompt in `session_meta.payload.base_instructions.text`
  (~15 KB), so the rollout's first line far exceeds the 8 KB fixed buffer
  `readSessionMeta` used. The truncated read failed `JSON.parse` → returned null →
  `detectCurrentCodexSession` found nothing → auto-relay fell back to resuming the
  **channel UUID**, which `codex exec resume` rejects ("no rollout found"). Net
  effect: every directed-message auto-wake to a Codex peer failed. Now streams the
  first line in full (any length) via `readline`. Detection tests now use realistic
  >8 KB `session_meta` fixtures (the prior tiny fixtures hid the bug).

## 3.4.2 — 2026-05-26

### Fixed
- **Codex sandbox flags rejected by `codex exec resume`** — `execCodex`'s
  `sandboxArgs` emitted `--full-auto` (deprecated; warns on every wake) for the
  default, and `--sandbox <mode>` for explicit modes. `--sandbox` is a parent
  `codex exec` flag and is **rejected** by the `resume` subcommand (exit 2), so any
  `COGENT_CODEX_SANDBOX=read-only|workspace-write|danger-full-access` broke every
  auto-relay — same class of bug as the 3.4.1 `--color` fix. Now uses the
  non-deprecated `-c sandbox_mode=<mode>` config override. Default maps to
  `workspace-write`. Regression test asserts `--sandbox`/`--full-auto`/`--color`
  are never passed.

### Docs
- FAQ: a pre-existing manual `[mcp_servers.cogent]` in `~/.codex/config.toml`
  shadows the installed plugin (same server name), causing the Codex peer to
  register as `platform: cc` and directed messages to time out. Documented the
  cause and both fixes (remove the manual entry, or add `COGENT_PLATFORM=codex`).

## 3.4.1 — 2026-05-26

### Fixed
- **Codex auto-relay broken by `--color never`** — `execCodex` passed `--color never`
  to `codex exec resume`, but `--color` is only valid on the parent `codex exec`
  command; the `resume` subcommand rejects it with exit 2 ("unexpected argument").
  This broke every directed-message auto-relay to a Codex peer. Removed the flag
  (the agent's final message is captured via `-o <file>`, so terminal color is moot).
  Added a regression test asserting `--color` is never passed.

### Changed
- `cogent_create_session` config snippet is now platform-aware: includes
  `COGENT_PLATFORM` and `npx -y` so generated Codex configs register correctly.

## 3.4.0 — 2026-05-26

### Added
- **Codex plugin + marketplace** — one-command install for OpenAI Codex
  (`codex plugin marketplace add eaisdevelopment/cogent && codex plugin add cogent@cogent`),
  reaching install parity with the Claude Code plugin. Dual-format marketplace.
- **Codex auto-relay** — an idle Codex agent peer now auto-replies to directed
  messages via `codex exec resume --full-auto`, matching Claude Code behavior.
  New config: `COGENT_CODEX_PATH`, `COGENT_CODEX_SANDBOX` (default `full-auto`).

### Changed
- Auto-relay execution is now platform-polymorphic (`execRemote`) keyed off the
  local peer's `COGENT_PLATFORM`.

## 3.3.0 — Multi-Provider: OpenAI Codex (2026-05-25)

### Added
- **Codex as first-class platform**: `platform: "codex"` in shared types, peer
  registration, and message origin tracking
- **`COGENT_PLATFORM` env var**: clients identify their platform (default `"cc"`;
  Codex sets `codex`). Replaces the hardcoded `platform: "cc"` in HttpBackend
- **Platform-segmented admin stats**: live agents-by-platform counts + cumulative
  historical totals (persisted to `platform-stats.json`)
- **Admin UI badges**: Platform and Mode columns in peer table (color-coded);
  platform breakdown in session list; agent-count cards on dashboard
- **Codex install instructions**: landing page, FAQ, README, docs/installation.md
- **Supported Platforms section** on landing page (Claude Code, Codex, Slack)
- **FAQ entries**: Codex setup, cross-platform messaging, model config, auto-relay status

### Changed
- All user-facing copy updated from "Claude Code" to platform-inclusive language
- `@essentialai/cogent` bumped to 3.1.0 (additive enum extension)
- Server package bumped from 3.2.1 to 3.3.0

### Not included (v3.4)
- Codex auto-relay adapter (`codex exec resume` subprocess dispatch)

## [3.2.2] - 2026-05-19

Surfaced by ~4-day clone-detector channel observer watch (tick 89 mass re-register event at 2026-05-18T00:30:26Z). Two client-side polish fixes plus a long-deferred marketplace + plugin version sync. No emergency — bridge transport is otherwise operationally fine.

### Fixed
- **FIX-LABEL-PRESERVE: preserve operator-supplied label + mode on auto-reconnect.** `AutoRelayService` now captures `label` and `mode` at `setLocalPeer()` time and surfaces both via `getLocalPeer()`. `triggerReRegistration()` in `src/startup.ts` passes the captured `label` (not `peerId`) and `mode` (not implicit `"agent"`) to `backend.registerPeer()` on auto-reconnect. Pre-3.2.2, the re-register call substituted `peerId` for `label` (silently normalizing `"Cogent_Master"` -> `"cogent-master"` after a WS-cycle mass-reregister) and dropped `mode` (silently flipping observer peers back to agent mode). See `src/services/auto-relay.ts`, `src/tools/register-peer.ts`, `src/startup.ts`.
- **FIX-WSHEALTH-RECONNECTING: new transient "reconnecting" state on health-check.** `transport.wsHealth` now has a fourth value, `"reconnecting"`, returned when `wsConnected=false` BUT the last frame was received within `COGENT_WS_STALE_MS` (default 90s). Pre-3.2.2 reported `"disconnected"` during the 1-4s window each ~5-20min keepalive cycle takes — alarming on a healthy idle channel. Only sustained socket-down beyond the threshold (or null last-frame) is now reported as `"disconnected"`. See `src/tools/health-check.ts`.

### Changed
- **`AutoRelayService.setLocalPeer()` signature** gained a 5th optional `label?: string` parameter (defaults to `peerId` for back-compat). `getLocalPeer()` return type widened to include `label: string` and `mode: "observer" | "agent"` so re-registration can replay the original registration payload exactly.

### Marketplace + manifests
- **`server.json` bumped 3.1.11 -> 3.2.2.** Top-level `version` + `packages[].version`. Was 4 minor-releases behind the npm package after Phase 17 / Phase 18 light shipped without a marketplace sync — operators installing via the MCP registry could not consume `metadataOnly` history or `dedupInferredEchoes` because the registry advertised pre-feature versions.
- **`plugin/.claude-plugin/plugin.json` bumped 3.1.8 -> 3.2.2.** Same story for the Claude Code plugin marketplace at `eaisdevelopment/cogent` — was 6 minor-releases behind. Plugin sync will land in the marketplace repo as part of this release deploy.

### Internal
- 5 new tests under `src/services/auto-relay.test.ts` covering label preservation, peerId-fallback for pre-3.2.2 callers, observer-mode preservation, and `stop()` clearing `localLabel`.
- 2 new tests under `src/tools/health-check.test.ts` covering the new `"reconnecting"` state (recent frame, socket down) and the boundary case where an old frame plus socket-down still resolves to `"disconnected"`.
- Existing `src/startup.test.ts triggerReRegistration` test updated to assert the new 6-arg `registerPeer` call (peerId, sessionId, cwd, label, clientVersion, mode); added one new test for observer-mode preservation through the re-register path.

Observability backstory: `temp/watch/cogent-watch-state.json` ticks 70-94 (4-day continuous watch as cogent-master; mass-reregister event at tick 89 surfaced both the label-strip regression and the wsHealth UX issue).

## [3.2.1] - 2026-05-17

Surfaced by 51-tick clone-detector channel watch (20 confirmed sender-side 180s timeouts, 9 confirmed untagged-echo phantoms across the session's 899-message history). Neither is a relay drop — both are receipt-side UX bugs that misled the LLM reading the bridge output.

### Fixed
- **FIX-TIMEOUT-UX: cloud-mode send-message timeout result shape.** Both timeout paths (`DELIVERY_NO_ACK` after 15s ack-wait, `RESPONSE_TIMEOUT` after `COGENT_TIMEOUT_MS` response-wait) now return `{success: false, timedOut: true, error: "DELIVERY_NO_ACK" | "RESPONSE_TIMEOUT", message: <stub-text>, response: null, durationMs}` instead of the prior `{success: true, response: <stub-text>}`. The LLM no longer mistakes the bridge's "Delivered to X but no synchronous response within 180s" stub for the recipient's actual reply. The history record's `response` field is also written as `null` on timeout (was the stub text), so later inspection cleanly distinguishes "no reply received" from "real reply received." See `src/tools/send-message.ts`.
- **FIX-INFERRED-ECHO: server-side dedup of untagged auto-relay echoes (Phase 18 light).** New optional GET param on `/api/sessions/:id/messages` — `dedupInferredEchoes` (default `false`). When `true`, suppresses M[i] when `M[i].message === M[i-1].response`, `M[i].fromPeerId === M[i-1].toPeerId`, `M[i].toPeerId === M[i-1].fromPeerId`, AND `Δt < 120s`. Catches the ~13% of echo records that bypass the `isRelayEcho` tag (peer-driven `cogent_send_message` re-broadcasts after autoRelay's execClaude returns). Opt-in to avoid surprise behavior change. Plumbed through `cogent_get_history` (new `dedupInferredEchoes: boolean` param) → `StorageBackend.getHistory(..., dedupInferredEchoes?)` → `HttpBackend` (sends `?dedupInferredEchoes=true` to server). `FileBackend` ignores the flag (local mode doesn't synthesize untagged echoes). See `server/src/routes/messages.ts`, `src/tools/get-history.ts`, `src/backend/*.ts`.

### Changed
- **`StorageBackend.updateMessageResponse(messageId, response, durationMs)`** signature: `response: string` → `response: string | null`. Server PATCH route mirrors with `z.string().nullable()`. Lets cloud clients explicitly mark timed-out sends with `null` response (was previously a misleading stub string).

### Internal
- 2 new tests under `src/tools/send-message.test.ts` `describe("cloud-mode timeout result shape (v3.2.1)")` — assert `success:false`, `timedOut:true`, `error: "DELIVERY_NO_ACK" | "RESPONSE_TIMEOUT"`, `response: null`, and that explanatory text lives in `message` not `response`. Spies on `isCloudMode` + `autoRelay.waitForDeliveryAck` / `waitForResponse` to drive the cloud path without booting `HttpBackend`.
- 5 new tests under `server/src/__tests__/routes/messages.test.ts` `describe("dedupInferredEchoes (FIX-INFERRED-ECHO, 3.2.1)")` — happy-path suppression, default-off backward compat, content-mismatch no-op, direction-mismatch no-op, string `"true"` preprocess coercion.

Observability backstory: `.planning/notes/` (`temp/watch/cogent-watch-state.json` raw evidence).

## [3.2.0] - 2026-05-12

### Added
- **Observer-mode peer registration (OBS-01).** `cogent_register_peer` accepts optional `mode: "observer" | "agent"` (default `"agent"`). Observer peers register normally and remain visible/targetable but skip the auto-relay subprocess. See `src/tools/register-peer.ts`, `src/services/auto-relay.ts`.
- **Observer mode surfaced via list-peers (OBS-02).** `cogent_list_peers` passes through the `mode` field via the existing `PeerInfo` spread. Operators can identify observer peers in the topology before sending. See `src/tools/list-peers.ts`, `src/types.ts`.
- **Auto-relay observer short-circuit (OBS-03).** `AutoRelayService.handleIncoming` short-circuits AFTER delivery-ack and waiter resolution, BEFORE `_processMessage` — observers ack frames and resolve their own outbound waiters, but never spawn `execClaude`. Extracted as `_shouldSkipAutoRelay()` for Phase 20 presence/DND reuse. See `src/services/auto-relay.ts`.
- **Metadata-only history schema (HIST-01).** `cogent_get_history` accepts optional `metadataOnly: boolean` (default `false`). Plumbs through `StorageBackend.getHistory(..., metadataOnly?)` to both `FileBackend` (client-side projection) and `HttpBackend` (server-side projection via `?metadataOnly=true` query param). See `src/tools/get-history.ts`, `src/backend/*.ts`.
- **Metadata-only 7-key projection (HIST-02).** When `metadataOnly: true`, each record is exactly `{id, fromPeerId, toPeerId, timestamp, durationMs, isRelayEcho, success}` — `message` and `response` keys are physically absent (object-literal projection, not delete-on-clone). Measured 94.4% payload reduction for a 30-record window (5.6% ratio vs ≤10% target). See `src/services/peer-registry.ts`, `server/src/routes/messages.ts`.
- **`transport.relayVersion` on health-check (VER-02).** Cloud mode populates `transport.relayVersion` from a lazy `GET /api/health` fetch behind a 60s module-scoped TTL cache (`src/backend/relay-version-cache.ts`). Relay upgrades become client-visible within 60s without a client restart. Returns `null` on fetch failure (rest of payload intact); key omitted entirely in local mode. See `src/tools/health-check.ts`, `src/backend/http-backend.ts`.

### Changed
- **Hard rename: `serverVersion` → `mcpServerVersion` (VER-01).** Top-level field on `cogent_health_check` renamed without a backward-compat alias. This is the local cogent-bridge npm package version (NOT the upstream relay; the relay's version is now in `transport.relayVersion`). **Breaking by omission:** mixed-version 3.1.x clients reading the old name will see `undefined` — intentional per the coordinated 3.2.0 bump. See `src/services/health-check.ts`, `src/backend/http-backend.ts`, `src/tools/health-check.ts`.

### Internal
- New module `src/backend/relay-version-cache.ts` with injectable `nowFn` clock seam and `__resetCacheForTest()` helper for deterministic TTL tests. Module-scoped `TTL_MS = 60_000` constant.
- 10 new tests under `src/services/auto-relay.test.ts` `describe("observer mode (OBS-03)")` and 6 new tests under `src/tools/health-check.test.ts` `describe("version field hygiene (VER-01 / VER-02)")`.
- 4 new tests under `src/tools/get-history.test.ts` `describe("metadataOnly (HIST-02)")` including a backend-layer size-ratio assertion (`≤0.10`).
- 5 new tests under `src/backend/relay-version-cache.test.ts` covering cold fetch, warm fetch, TTL expiry, fetch-error no-cache, and malformed-payload no-cache.

Planning: `.planning/phases/17-observer-mode-and-history-hygiene/`

## [3.1.5] - 2026-05-05

### Fixed
- **Empty-body DELETE peer interop bug.** `HttpClient.delete()` always set `Content-Type: application/json` regardless of whether a body was actually sent. When a third-party client (curl, custom probe scripts, the `temp/cogent-probe-scheduler.mjs` we ship) called `DELETE /api/sessions/<id>/peers/<peerId>` without a body, cogent-server <=3.1.2 attempted to JSON-parse the empty payload and returned `400 "Malformed JSON in request body"`. Client now omits the `Content-Type` header when no body is provided. Companion server fix lands in `cogent-server@3.1.3`.

## [3.1.4] - 2026-05-04

### Fixed
- **False-offline reports during active dialogue (root cause).** `AutoRelayService.handleIncoming()` returned without emitting a `delivery_ack` whenever an inbound message resolved a pending `responseWaiters` entry. When two peers were mutually awaiting responses (the normal pattern in active conversation), their cross-delivered messages each consumed the recipient's waiter and skipped the ack. The sender's 15-second ack-wait then timed out, and `cogent_send_message` reported the recipient as offline — even though both peers were connected and the message had been delivered. The ack call is now hoisted to the top of `handleIncoming()` so every accepted frame produces an ack regardless of subsequent routing.
- **Send-message supersession returning a placeholder string.** Calling `waitForResponse()` for the same peer twice (two in-flight `cogent_send_message` calls) used to resolve the first waiter with the literal string `"Superseded by newer send_message call"`, which was then surfaced to the LLM as the peer's response. Replaced single-slot waiter Map with a FIFO queue per peer: each in-flight send gets its own waiter, inbound messages from that peer resolve waiters in send order, and `_cancelWaiter()` now rejects with a clear error instead of fabricating a fake response.
- **Misleading timeout copy in `cogent_send_message`.** The 15-second ack-timeout error said `"appears offline. Check cogent_get_history for their reply"` and the 5-minute response timeout said `"Processing timed out -- check cogent_get_history"`. Both prompted the LLM to rationalise the timeout as the peer being offline. The error text now reports the relay's actual `lastSeenAt` for the peer and explicitly mentions that a reply may have arrived as a fresh `cogent_send_message` rather than the synchronous response pattern.

### Added
- New regression tests in `src/services/auto-relay.test.ts`:
  - FIFO waiter queue: two send-messages to the same peer each get their own response in send order.
  - Supersession placeholder: `"Superseded by newer send_message call"` no longer leaks to callers.
  - Delivery-ack-on-waiter-resolution: messages that resolve an active waiter still produce an ack frame.

## [3.0.6] - 2026-03-21

### Fixed
- Stale peer recovery: server heartbeat now returns 404 (PEER_NOT_FOUND) when a peer has been evicted by stale cleanup, instead of silently returning 204. This allows clients to detect eviction.
- Client auto-recovers from stale peer eviction: HeartbeatService detects the 404 response and triggers automatic re-registration + WS reconnection without manual intervention.
- WebSocket client detects 404 on upgrade rejection (peer evicted) and invokes onPeerEvicted callback instead of entering an infinite reconnect loop.
- Added debounced `triggerReRegistration()` in startup.ts that coordinates re-registration, WS reconnection, and heartbeat restart.

## [3.0.5] - 2026-03-20

### Fixed
- Idle relay failure after ~1hr of silence: `autoRelay.localSessionId` was set once at registration and never refreshed. Claude Code rotates its `.jsonl` session file after long idle periods, making the stored session ID stale and causing `claude --resume <stale-id>` to inject messages into a dead session.
- Added `detectCurrentSession(cwd)` utility that dynamically finds the most recently modified `.jsonl` project file before each relay attempt.
- `AutoRelayService` now refreshes the session ID before every `execClaude()` call and retries once on stale detection.
- `HeartbeatService` proactively refreshes the session ID every 60s to avoid staleness accumulating silently.
- `register-peer.ts` refactored to use shared `detectCurrentSession()` instead of inline synchronous FS logic.

## [3.0.0] - 2026-03-19

### Added
- Multi-platform adapter support: CC peers now register with platform:"cc", type:"agent", transport:"ws"
- HttpBackend sends platform/type/transport fields in registerPeer POST body
- Compatibility with server v3.0 adapter infrastructure and Slack integration

### Changed
- Depends on @essentialai/cogent ^3.0.0 (extended PeerInfo and MessageRecord types)

## [2.0.3] - 2026-03-12

### Fixed
- `cogent_get_history` no longer overflows Claude Code's MCP result size limit. Responses are now capped at 50,000 characters, keeping the newest messages and trimming oldest when history is large (long AI responses, code blocks). Returns `truncated` and `totalAvailable` fields when trimming occurs.
- Default message fetch limit reduced from 150 to 30; tool description no longer discourages using a smaller limit.

## [2.0.2] - 2026-03-11

### Added
- Two-stage delivery acknowledgment in cloud mode: `send-message` now reports whether the recipient's MCP actually received the message (delivery ack), not just whether the relay server accepted it.
- Distinct timeout messages: "Delivered to recipient's Cogent MCP. Processing timed out" vs "Message accepted by relay but recipient appears offline".

### Changed
- Landing page and how-to guide updated with instructions for updating the bridge.

## [2.0.1] - 2026-03-11

### Fixed
- Cloud mode detection used frozen config value instead of runtime backend state, causing `send-message` to behave as local mode even after cloud registration.
- WebSocket connection was not triggered on peer registration in cloud mode (same root cause).

## [2.0.0] - 2026-02-25

### Added
- Cloud mode: connect to cogent.tools relay server for cross-machine communication
- HttpBackend for REST API integration with cloud relay
- WebSocket client for real-time message push with reconnection
- Session create/join tools for cloud session management
- Auto-relay: send-message blocks until response arrives in cloud mode
- Label-based session joining with auto-generated human-readable labels
- Interactive setup wizard (`cogent-bridge init`)

### Changed
- Transport abstraction: StorageBackend interface with FileBackend (local) and HttpBackend (cloud)
- License changed from ISC to Apache 2.0

### Fixed
- Cloud message delivery reliability via auto-relay service
- Session isolation between concurrent cloud sessions