@essentialai/cogent-bridge 3.1.11 → 3.2.2

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## [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

package/dist/backend/file-backend.d.ts

@@ -8,13 +8,13 @@ import { StorageBackend } from "./storage-backend.js";
  * cc-cli.ts, and health-check.ts. No added logic, logging, or transformation.
  */
 export declare class FileBackend implements StorageBackend {
-    registerPeer(peerId: string, sessionId: string, cwd: string, label: string, clientVersion?: string): Promise<PeerInfo>;
+    registerPeer(peerId: string, sessionId: string, cwd: string, label: string, clientVersion?: string, mode?: "observer" | "agent"): Promise<PeerInfo>;
     deregisterPeer(peerId: string): Promise<boolean>;
     getPeer(peerId: string): Promise<PeerInfo | undefined>;
     listPeers(): Promise<PeerInfo[]>;
     updateLastSeen(peerId: string): Promise<void>;
     recordMessage(record: Omit<MessageRecord, "id" | "timestamp">): Promise<MessageRecord>;
-    getHistory(peerId?: string, limit?: number, includeRelayEchoes?: boolean): Promise<MessageRecord[]>;
+    getHistory(peerId?: string, limit?: number, includeRelayEchoes?: boolean, metadataOnly?: boolean, _dedupInferredEchoes?: boolean): Promise<MessageRecord[]>;
     validateSession(sessionId: string, cwd: string): Promise<boolean>;
     execClaude(sessionId: string, message: string, cwd: string, timeoutMs?: number): Promise<CliExecResult>;
     checkHealth(): Promise<HealthCheckResult>;

package/dist/backend/file-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-backend.d.ts","sourceRoot":"","sources":["../../src/backend/file-backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAKtD;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,cAAc;IAGhD,YAAY,CACV,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,QAAQ,CAAC;IAIpB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIhD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAItD,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIhC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7C,aAAa,CACX,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,WAAW,CAAC,GAC9C,OAAO,CAAC,aAAa,CAAC;IAIzB,UAAU,CACR,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,EACd,kBAAkB,CAAC,EAAE,OAAO,GAC3B,OAAO,CAAC,aAAa,EAAE,CAAC;IAM3B,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIjE,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC;IAMzB,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAG1C"}
+{"version":3,"file":"file-backend.d.ts","sourceRoot":"","sources":["../../src/backend/file-backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAKtD;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,cAAc;IAGhD,YAAY,CACV,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,GAC1B,OAAO,CAAC,QAAQ,CAAC;IAWpB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIhD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAItD,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIhC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7C,aAAa,CACX,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,WAAW,CAAC,GAC9C,OAAO,CAAC,aAAa,CAAC;IAIzB,UAAU,CACR,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,EACd,kBAAkB,CAAC,EAAE,OAAO,EAC5B,YAAY,CAAC,EAAE,OAAO,EACtB,oBAAoB,CAAC,EAAE,OAAO,GAC7B,OAAO,CAAC,aAAa,EAAE,CAAC;IAQ3B,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIjE,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC;IAMzB,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAG1C"}

package/dist/backend/file-backend.js

@@ -9,8 +9,8 @@ import * as health from "../services/health-check.js";
  */
 export class FileBackend {
     // --- Peer management ---
-    registerPeer(peerId, sessionId, cwd, label, clientVersion) {
-        return registry.registerPeer(peerId, sessionId, cwd, label, clientVersion);
+    registerPeer(peerId, sessionId, cwd, label, clientVersion, mode) {
+        return registry.registerPeer(peerId, sessionId, cwd, label, clientVersion, mode);
     }
     deregisterPeer(peerId) {
         return registry.deregisterPeer(peerId);
@@ -28,8 +28,10 @@ export class FileBackend {
     recordMessage(record) {
         return registry.recordMessage(record);
     }
-    getHistory(peerId, limit, includeRelayEchoes) {
-        return registry.getHistory(peerId, limit, includeRelayEchoes);
+    getHistory(peerId, limit, includeRelayEchoes, metadataOnly, _dedupInferredEchoes) {
+        // Local FileBackend doesn't synthesize untagged echoes (no autoRelay
+        // re-broadcast pattern), so dedupInferredEchoes is a no-op here.
+        return registry.getHistory(peerId, limit, includeRelayEchoes, metadataOnly);
     }
     // --- Message relay ---
     validateSession(sessionId, cwd) {

package/dist/backend/file-backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-backend.js","sourceRoot":"","sources":["../../src/backend/file-backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,QAAQ,MAAM,8BAA8B,CAAC;AACzD,OAAO,KAAK,GAAG,MAAM,uBAAuB,CAAC;AAC7C,OAAO,KAAK,MAAM,MAAM,6BAA6B,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IACtB,0BAA0B;IAE1B,YAAY,CACV,MAAc,EACd,SAAiB,EACjB,GAAW,EACX,KAAa,EACb,aAAsB;QAEtB,OAAO,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;IAC7E,CAAC;IAED,cAAc,CAAC,MAAc;QAC3B,OAAO,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,CAAC,MAAc;QACpB,OAAO,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,SAAS;QACP,OAAO,QAAQ,CAAC,SAAS,EAAE,CAAC;IAC9B,CAAC;IAED,cAAc,CAAC,MAAc;QAC3B,OAAO,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED,wBAAwB;IAExB,aAAa,CACX,MAA+C;QAE/C,OAAO,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,UAAU,CACR,MAAe,EACf,KAAc,EACd,kBAA4B;QAE5B,OAAO,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAC;IAChE,CAAC;IAED,wBAAwB;IAExB,eAAe,CAAC,SAAiB,EAAE,GAAW;QAC5C,OAAO,GAAG,CAAC,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED,UAAU,CACR,SAAiB,EACjB,OAAe,EACf,GAAW,EACX,SAAkB;QAElB,OAAO,GAAG,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC5D,CAAC;IAED,iBAAiB;IAEjB,WAAW;QACT,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC;IAC9B,CAAC;CACF"}
+{"version":3,"file":"file-backend.js","sourceRoot":"","sources":["../../src/backend/file-backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,QAAQ,MAAM,8BAA8B,CAAC;AACzD,OAAO,KAAK,GAAG,MAAM,uBAAuB,CAAC;AAC7C,OAAO,KAAK,MAAM,MAAM,6BAA6B,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IACtB,0BAA0B;IAE1B,YAAY,CACV,MAAc,EACd,SAAiB,EACjB,GAAW,EACX,KAAa,EACb,aAAsB,EACtB,IAA2B;QAE3B,OAAO,QAAQ,CAAC,YAAY,CAC1B,MAAM,EACN,SAAS,EACT,GAAG,EACH,KAAK,EACL,aAAa,EACb,IAAI,CACL,CAAC;IACJ,CAAC;IAED,cAAc,CAAC,MAAc;QAC3B,OAAO,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,CAAC,MAAc;QACpB,OAAO,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,SAAS;QACP,OAAO,QAAQ,CAAC,SAAS,EAAE,CAAC;IAC9B,CAAC;IAED,cAAc,CAAC,MAAc;QAC3B,OAAO,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED,wBAAwB;IAExB,aAAa,CACX,MAA+C;QAE/C,OAAO,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,UAAU,CACR,MAAe,EACf,KAAc,EACd,kBAA4B,EAC5B,YAAsB,EACtB,oBAA8B;QAE9B,qEAAqE;QACrE,iEAAiE;QACjE,OAAO,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,YAAY,CAAC,CAAC;IAC9E,CAAC;IAED,wBAAwB;IAExB,eAAe,CAAC,SAAiB,EAAE,GAAW;QAC5C,OAAO,GAAG,CAAC,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED,UAAU,CACR,SAAiB,EACjB,OAAe,EACf,GAAW,EACX,SAAkB;QAElB,OAAO,GAAG,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC5D,CAAC;IAED,iBAAiB;IAEjB,WAAW;QACT,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC;IAC9B,CAAC;CACF"}

package/dist/backend/http-backend.d.ts

@@ -26,7 +26,7 @@ export declare class HttpBackend implements StorageBackend {
      * The sessionId parameter from StorageBackend is the local CC sessionId;
      * in cloud mode we ignore it and use this.sessionId (the cloud session).
      */
-    registerPeer(peerId: string, _sessionId: string, cwd: string, label: string, clientVersion?: string): Promise<PeerInfo>;
+    registerPeer(peerId: string, _sessionId: string, cwd: string, label: string, clientVersion?: string, mode?: "observer" | "agent"): Promise<PeerInfo>;
     /**
      * Deregister a peer from the cloud session.
      * DELETE /api/sessions/:sessionId/peers/:peerId
@@ -65,7 +65,7 @@ export declare class HttpBackend implements StorageBackend {
      *
      * Supports optional peerId filter and limit (default 300).
      */
-    getHistory(peerId?: string, limit?: number, includeRelayEchoes?: boolean): Promise<MessageRecord[]>;
+    getHistory(peerId?: string, limit?: number, includeRelayEchoes?: boolean, metadataOnly?: boolean, dedupInferredEchoes?: boolean): Promise<MessageRecord[]>;
     /**
      * Update an existing message record's response field on the server.
      * PATCH /api/sessions/:sessionId/messages/:messageId
@@ -73,7 +73,7 @@ export declare class HttpBackend implements StorageBackend {
      * Called by send-message after receiving the async cloud response,
      * so that get-history shows the actual response (not null).
      */
-    updateMessageResponse(messageId: string, response: string, durationMs: number): Promise<void>;
+    updateMessageResponse(messageId: string, response: string | null, durationMs: number): Promise<void>;
     /**
      * Validate a session.
      * In cloud mode, the server validates session authenticity on every
@@ -97,5 +97,16 @@ export declare class HttpBackend implements StorageBackend {
      * format with cloud-mode-specific diagnostics.
      */
     checkHealth(): Promise<HealthCheckResult>;
+    /**
+     * Lazy lookup of the upstream relay's `version` field via GET /api/health,
+     * memoized for 60s. Returns null on fetch failure or malformed payload.
+     * Never throws — the caller (health-check tool) treats null as "unknown"
+     * and keeps the rest of the response intact.
+     *
+     * Delegates to the module-scoped cache in `relay-version-cache.ts` so the
+     * TTL is shared across all callers and tests can reset state via
+     * `__resetCacheForTest()`. VER-02 (3.2).
+     */
+    getRelayVersion(): Promise<string | null>;
 }
 //# sourceMappingURL=http-backend.d.ts.map

package/dist/backend/http-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-backend.d.ts","sourceRoot":"","sources":["../../src/backend/http-backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAgB1D;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAY,YAAW,cAAc;IAE9C,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM;IAGpC;;;;;;OAMG;IACG,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,QAAQ,CAAC;IAmBpB;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAatD;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAK5D;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAMtC;;;OAGG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnD;;;;;;;OAOG;IACG,aAAa,CACjB,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,WAAW,CAAC,GAC9C,OAAO,CAAC,aAAa,CAAC;IA2BzB;;;;;OAKG;IACG,UAAU,CACd,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,EACd,kBAAkB,CAAC,EAAE,OAAO,GAC3B,OAAO,CAAC,aAAa,EAAE,CAAC;IAsB3B;;;;;;OAMG;IACG,qBAAqB,CACzB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAOhB;;;;OAIG;IACG,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC;IAInB;;;;;;;OAOG;IACG,UAAU,CACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,CAAC;IAQzB;;;;;;OAMG;IACG,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAoChD"}
+{"version":3,"file":"http-backend.d.ts","sourceRoot":"","sources":["../../src/backend/http-backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAiB1D;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAY,YAAW,cAAc;IAE9C,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM;IAGpC;;;;;;OAMG;IACG,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,GAC1B,OAAO,CAAC,QAAQ,CAAC;IA2BpB;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAatD;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAK5D;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAMtC;;;OAGG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnD;;;;;;;OAOG;IACG,aAAa,CACjB,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,WAAW,CAAC,GAC9C,OAAO,CAAC,aAAa,CAAC;IA2BzB;;;;;OAKG;IACG,UAAU,CACd,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,EACd,kBAAkB,CAAC,EAAE,OAAO,EAC5B,YAAY,CAAC,EAAE,OAAO,EACtB,mBAAmB,CAAC,EAAE,OAAO,GAC5B,OAAO,CAAC,aAAa,EAAE,CAAC;IAmC3B;;;;;;OAMG;IACG,qBAAqB,CACzB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAOhB;;;;OAIG;IACG,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC;IAInB;;;;;;;OAOG;IACG,UAAU,CACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,CAAC;IAQzB;;;;;;OAMG;IACG,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAyC/C;;;;;;;;;OASG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAGhD"}

package/dist/backend/http-backend.js

@@ -1,4 +1,5 @@
 import { SERVER_VERSION } from "../constants.js";
+import { getRelayVersion } from "./relay-version-cache.js";
 /**
  * API path patterns matching @essentialai/cogent PATHS constants.
  * Defined locally because cogent is not a dependency of the main package.
@@ -38,7 +39,7 @@ export class HttpBackend {
      * The sessionId parameter from StorageBackend is the local CC sessionId;
      * in cloud mode we ignore it and use this.sessionId (the cloud session).
      */
-    async registerPeer(peerId, _sessionId, cwd, label, clientVersion) {
+    async registerPeer(peerId, _sessionId, cwd, label, clientVersion, mode) {
         const path = PATHS.peers.replace(":sessionId", this.sessionId);
         // Build body conditionally: omit clientVersion entirely for older clients
         // / undefined inputs so the wire payload stays clean (no JSON null) and
@@ -54,6 +55,14 @@ export class HttpBackend {
         if (clientVersion !== undefined) {
             body.clientVersion = clientVersion;
         }
+        // Same omit-when-undefined pattern for the 3.2.0 mode field (Phase 17
+        // OBS-01). Older servers that don't know the field will ignore it (it
+        // arrives via the .strict() body schema, so a pre-3.2.0 server WOULD
+        // reject the request — guarded by the optional field on the server
+        // mirror being shipped in lockstep with the client).
+        if (mode !== undefined) {
+            body.mode = mode;
+        }
         return this.http.post(path, body);
     }
     /**
@@ -136,7 +145,7 @@ export class HttpBackend {
      *
      * Supports optional peerId filter and limit (default 300).
      */
-    async getHistory(peerId, limit, includeRelayEchoes) {
+    async getHistory(peerId, limit, includeRelayEchoes, metadataOnly, dedupInferredEchoes) {
         const path = PATHS.messages.replace(":sessionId", this.sessionId);
         const query = {};
         if (peerId) {
@@ -150,6 +159,19 @@ export class HttpBackend {
         if (includeRelayEchoes) {
             query.includeRelayEchoes = "true";
         }
+        // HIST-02 (3.2): server projects the 7-key shape when this is set.
+        // Same omit-when-falsy pattern — pre-3.2 servers ignore the unknown
+        // key and return full records, so client-side parsers must not assume
+        // the projection is enforced.
+        if (metadataOnly) {
+            query.metadataOnly = "true";
+        }
+        // FIX-INFERRED-ECHO (3.2.1): server filters untagged auto-relay echoes
+        // via content-and-direction heuristic when this is set. Older servers
+        // (pre-3.2.1) ignore the unknown key.
+        if (dedupInferredEchoes) {
+            query.dedupInferredEchoes = "true";
+        }
         const result = await this.http.get(path, query);
         return result.messages;
     }
@@ -200,7 +222,11 @@ export class HttpBackend {
         const resp = await this.http.get(PATHS.health);
         return {
             healthy: resp.status === "ok",
-            serverVersion: SERVER_VERSION,
+            // VER-01 (3.2): the SERVER_VERSION constant still identifies the local
+            // cogent-bridge npm package — this property name makes its role
+            // unambiguous now that transport.relayVersion carries the upstream
+            // relay's version. Hard rename, no backward-compat alias.
+            mcpServerVersion: SERVER_VERSION,
             statePath: "cloud:" + this.sessionId,
             claudePath: "N/A (cloud mode)",
             checks: {
@@ -225,5 +251,18 @@ export class HttpBackend {
             serverUptime: resp.uptime,
         };
     }
+    /**
+     * Lazy lookup of the upstream relay's `version` field via GET /api/health,
+     * memoized for 60s. Returns null on fetch failure or malformed payload.
+     * Never throws — the caller (health-check tool) treats null as "unknown"
+     * and keeps the rest of the response intact.
+     *
+     * Delegates to the module-scoped cache in `relay-version-cache.ts` so the
+     * TTL is shared across all callers and tests can reset state via
+     * `__resetCacheForTest()`. VER-02 (3.2).
+     */
+    async getRelayVersion() {
+        return getRelayVersion(this.http);
+    }
 }
 //# sourceMappingURL=http-backend.js.map

package/dist/backend/http-backend.js.map

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

package/dist/backend/relay-version-cache.d.ts

@@ -0,0 +1,17 @@
+import type { HttpClient } from "../cloud/http-client.js";
+/**
+ * Get the relay's version, using a 60s TTL cache. Returns null on fetch
+ * failure or malformed response. Does not throw.
+ *
+ * @param http  Authenticated HttpClient (typically `HttpBackend.http`).
+ * @param nowFn Override for `Date.now()` (test seam). Defaults to `Date.now`.
+ */
+export declare function getRelayVersion(http: HttpClient, nowFn?: () => number): Promise<string | null>;
+/**
+ * Test-only helper to clear the module-scoped cache. Call from beforeEach
+ * in test suites that exercise the cache.
+ *
+ * @internal
+ */
+export declare function __resetCacheForTest(): void;
+//# sourceMappingURL=relay-version-cache.d.ts.map

package/dist/backend/relay-version-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-version-cache.d.ts","sourceRoot":"","sources":["../../src/backend/relay-version-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAmC1D;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,UAAU,EAChB,KAAK,GAAE,MAAM,MAAiB,GAC7B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}

package/dist/backend/relay-version-cache.js

@@ -0,0 +1,65 @@
+import { logger } from "../logger.js";
+/**
+ * Module-scoped cache for the relay's `version` field (from GET /api/health).
+ *
+ * Rationale (VER-02, plan 17-03):
+ * - Operators need to see "is my relay current?" at a glance via cogent_health_check.
+ * - A hot-path HTTP call on every health_check is too expensive.
+ * - A 60s TTL bounds staleness: relay upgrades become visible to the client
+ *   within 60s without a client restart, but the fetch is amortized across
+ *   N calls within the window.
+ *
+ * Failure semantics:
+ * - On HTTP error: return null, DO NOT cache. Next call retries.
+ * - On malformed payload (no `version` string): return null, DO NOT cache.
+ * - Caller (health-check tool) treats null as "unknown" — does NOT propagate
+ *   the fetch failure upward; the rest of the health_check response is intact.
+ *
+ * Test seam:
+ * - `nowFn` parameter (default `Date.now`) lets tests advance the clock
+ *   deterministically without coupling to vitest fake-timer state shared
+ *   across other suites.
+ * - `__resetCacheForTest()` clears module state between tests.
+ */
+const TTL_MS = 60_000;
+let cached = null;
+/**
+ * Get the relay's version, using a 60s TTL cache. Returns null on fetch
+ * failure or malformed response. Does not throw.
+ *
+ * @param http  Authenticated HttpClient (typically `HttpBackend.http`).
+ * @param nowFn Override for `Date.now()` (test seam). Defaults to `Date.now`.
+ */
+export async function getRelayVersion(http, nowFn = Date.now) {
+    const now = nowFn();
+    if (cached !== null && now - cached.fetchedAt < TTL_MS) {
+        return cached.version;
+    }
+    try {
+        const resp = await http.get("/api/health");
+        const version = resp?.version;
+        if (typeof version !== "string" || version.length === 0) {
+            // Malformed response shape — treat as fetch failure. Do not cache.
+            logger.debug(`relay-version-cache: /api/health response missing string 'version' field`);
+            return null;
+        }
+        cached = { version, fetchedAt: now };
+        return version;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.debug(`relay-version-cache: /api/health fetch failed: ${msg}`);
+        // Do NOT update `cached` — next call retries.
+        return null;
+    }
+}
+/**
+ * Test-only helper to clear the module-scoped cache. Call from beforeEach
+ * in test suites that exercise the cache.
+ *
+ * @internal
+ */
+export function __resetCacheForTest() {
+    cached = null;
+}
+//# sourceMappingURL=relay-version-cache.js.map

package/dist/backend/relay-version-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-version-cache.js","sourceRoot":"","sources":["../../src/backend/relay-version-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,GAAG,MAAM,CAAC;AAOtB,IAAI,MAAM,GAAsB,IAAI,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAgB,EAChB,QAAsB,IAAI,CAAC,GAAG;IAE9B,MAAM,GAAG,GAAG,KAAK,EAAE,CAAC;IAEpB,IAAI,MAAM,KAAK,IAAI,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,GAAG,MAAM,EAAE,CAAC;QACvD,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAwB,aAAa,CAAC,CAAC;QAClE,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,CAAC;QAC9B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxD,mEAAmE;YACnE,MAAM,CAAC,KAAK,CACV,0EAA0E,CAC3E,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;QACrC,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,CAAC,KAAK,CAAC,kDAAkD,GAAG,EAAE,CAAC,CAAC;QACtE,8CAA8C;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC"}

package/dist/backend/storage-backend.d.ts

@@ -10,7 +10,9 @@ import { HealthCheckResult } from "../services/health-check.js";
 export interface StorageBackend {
     registerPeer(peerId: string, sessionId: string, cwd: string, label: string, 
     /** cogent-bridge client version sent by the registering process (3.1.6+). */
-    clientVersion?: string): Promise<PeerInfo>;
+    clientVersion?: string, 
+    /** Observer peers receive frames but never auto-respond, added in 3.2 (Phase 17 OBS-01). */
+    mode?: "observer" | "agent"): Promise<PeerInfo>;
     deregisterPeer(peerId: string): Promise<boolean>;
     getPeer(peerId: string): Promise<PeerInfo | undefined>;
     listPeers(): Promise<PeerInfo[]>;
@@ -23,12 +25,30 @@ export interface StorageBackend {
      * (FE->BE response mirrors). Defaults to false in implementations -- the
      * common case is a "clean" history with one record per directed exchange.
      * Added in 3.1.11 (260511-o3p).
+     * @param metadataOnly When true, records are returned with body fields
+     * (message, response) omitted — only id, fromPeerId, toPeerId, timestamp,
+     * durationMs, isRelayEcho, success kept. Added in 3.2 (HIST-02).
+     * @param dedupInferredEchoes When true, suppress untagged auto-relay echoes
+     * via content-and-direction heuristic. Cloud-backend-only; FileBackend
+     * ignores the flag. Added in 3.2.1 (FIX-INFERRED-ECHO).
      */
-    getHistory(peerId?: string, limit?: number, includeRelayEchoes?: boolean): Promise<MessageRecord[]>;
+    getHistory(peerId?: string, limit?: number, includeRelayEchoes?: boolean, metadataOnly?: boolean, dedupInferredEchoes?: boolean): Promise<MessageRecord[]>;
     validateSession(sessionId: string, cwd: string): Promise<boolean>;
     execClaude(sessionId: string, message: string, cwd: string, timeoutMs?: number): Promise<CliExecResult>;
-    /** Update an existing message record's response field. Optional -- only HttpBackend implements this. */
-    updateMessageResponse?(messageId: string, response: string, durationMs: number): Promise<void>;
+    /**
+     * Update an existing message record's response field. Optional -- only
+     * HttpBackend implements this. Pass `null` to mark a timed-out send so
+     * the record's response is not mistaken for the recipient's actual reply
+     * (v3.2.1, FIX-TIMEOUT-UX).
+     */
+    updateMessageResponse?(messageId: string, response: string | null, durationMs: number): Promise<void>;
     checkHealth(): Promise<HealthCheckResult>;
+    /**
+     * Lazy lookup of the upstream relay's `version` field, memoized for 60s
+     * by the implementing backend. Returns null in local mode or on fetch
+     * failure. Optional — only HttpBackend implements this; FileBackend omits.
+     * Added in 3.2 (VER-02). Consumers must use optional chaining.
+     */
+    getRelayVersion?(): Promise<string | null>;
 }
 //# sourceMappingURL=storage-backend.d.ts.map

package/dist/backend/storage-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-backend.d.ts","sourceRoot":"","sources":["../../src/backend/storage-backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAE7B,YAAY,CACV,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM;IACb,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IAEvD,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEjC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAG9C,aAAa,CACX,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,WAAW,CAAC,GAC9C,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B;;;;;;;OAOG;IACH,UAAU,CACR,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,EACd,kBAAkB,CAAC,EAAE,OAAO,GAC3B,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAG5B,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAElE,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAAC;IAG1B,wGAAwG;IACxG,qBAAqB,CAAC,CACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAAC;IAGjB,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC3C"}
+{"version":3,"file":"storage-backend.d.ts","sourceRoot":"","sources":["../../src/backend/storage-backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAE7B,YAAY,CACV,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM;IACb,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM;IACtB,4FAA4F;IAC5F,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,GAC1B,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IAEvD,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEjC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAG9C,aAAa,CACX,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,WAAW,CAAC,GAC9C,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B;;;;;;;;;;;;;OAaG;IACH,UAAU,CACR,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,EACd,kBAAkB,CAAC,EAAE,OAAO,EAC5B,YAAY,CAAC,EAAE,OAAO,EACtB,mBAAmB,CAAC,EAAE,OAAO,GAC5B,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAG5B,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAElE,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAAC;IAG1B;;;;;OAKG;IACH,qBAAqB,CAAC,CACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAAC;IAGjB,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE1C;;;;;OAKG;IACH,eAAe,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC5C"}

package/dist/services/auto-relay.d.ts

@@ -3,6 +3,27 @@ export declare class AutoRelayService {
     private localPeerId;
     private localSessionId;
     private localCwd;
+    /**
+     * Peer participation mode (3.2.0, Phase 17 OBS-03).
+     * - "agent" (default): full auto-relay — inbound directed messages run
+     *   through delivery-ack + queueing + execClaude.
+     * - "observer": short-circuit before delivery-ack and processing; the peer
+     *   is a passive watcher. Set by `setLocalPeer()` from the register-peer
+     *   tool when the operator passes `mode: "observer"`.
+     *
+     * Phase 20 will OR additional conditions (presence/DND/AFK) into the
+     * short-circuit check via the `_shouldSkipAutoRelay()` helper.
+     */
+    private localMode;
+    /**
+     * Human-readable label captured at register-peer time. Preserved here so
+     * triggerReRegistration() (startup.ts) can pass the original label on
+     * auto-reconnect after a server eviction or WS cycle, instead of falling
+     * back to the peerId. Closes the v3.2.1 label-normalization regression
+     * where 'Cogent_Master' silently became 'cogent-master' after the first
+     * mass-reregister event.
+     */
+    private localLabel;
     private processing;
     private queue;
     private expectingResponseFrom;
@@ -13,7 +34,18 @@ export declare class AutoRelayService {
      * Set the local peer info. Called from register-peer tool after
      * successful registration so we know which session to inject into.
      */
-    setLocalPeer(peerId: string, sessionId: string, cwd: string): void;
+    setLocalPeer(peerId: string, sessionId: string, cwd: string, mode?: "observer" | "agent", label?: string): void;
+    /**
+     * Internal predicate: should auto-relay short-circuit BEFORE delivery-ack,
+     * BEFORE waiter resolution, and BEFORE _processMessage spawns execClaude?
+     *
+     * Extracted as a method so Phase 20 (presence/DND/AFK) can OR additional
+     * conditions in here without rewriting handleIncoming. The short-circuit
+     * site is upstream of delivery-ack on purpose: observers are passive — the
+     * sender should not believe the message was "delivered to an agent that
+     * will act on it". (STATE.md blocker for Phase 20 reusability.)
+     */
+    private _shouldSkipAutoRelay;
     /**
      * Get the local peer info for re-registration after eviction.
      * Returns null if no peer has been registered yet.
@@ -22,6 +54,8 @@ export declare class AutoRelayService {
         peerId: string;
         sessionId: string;
         cwd: string;
+        label: string;
+        mode: "observer" | "agent";
     } | null;
     /**
      * Re-detect the current CC session from disk. If the session has rotated
@@ -127,6 +161,7 @@ export declare class AutoRelayService {
     getDiagnostics(): {
         registered: boolean;
         localPeerId: string | null;
+        mode: "observer" | "agent";
         processing: boolean;
         queueLength: number;
         expectingResponseFrom: string[];

package/dist/services/auto-relay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-relay.d.ts","sourceRoot":"","sources":["../../src/services/auto-relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAqD5C,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,qBAAqB,CAA0B;IAOvD,OAAO,CAAC,eAAe,CAIP;IAChB,OAAO,CAAC,kBAAkB,CAGX;IACf,OAAO,CAAC,iBAAiB,CAAoF;IAE7G;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAOlE;;;OAGG;IACH,YAAY,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAWzE;;;;OAIG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IASvC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAI/F;;;;;OAKG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKxC;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkCvE;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAU5B;;OAEG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAM1C;;;;OAIG;IACH,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAI9C;;OAEG;IACH,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIjD;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAUrB;;;;OAIG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxE;;;OAGG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAU5C;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAShC;;;;;;;;;;OAUG;IACG,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAqFvD;;OAEG;YACW,eAAe;IAgG7B;;;OAGG;YACW,WAAW;IAmCzB;;;OAGG;IACH,cAAc,IAAI;QAChB,UAAU,EAAE,OAAO,CAAC;QACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,UAAU,EAAE,OAAO,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,qBAAqB,EAAE,MAAM,EAAE,CAAC;QAChC,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,wBAAwB,EAAE,MAAM,EAAE,CAAC;KACpC;IAYD;;OAEG;IACH,IAAI,IAAI,IAAI;CA4Bb;AAED,0DAA0D;AAC1D,eAAO,MAAM,SAAS,kBAAyB,CAAC"}
+{"version":3,"file":"auto-relay.d.ts","sourceRoot":"","sources":["../../src/services/auto-relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAqD5C,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAuB;IACvC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,SAAS,CAAiC;IAClD;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,qBAAqB,CAA0B;IAOvD,OAAO,CAAC,eAAe,CAIP;IAChB,OAAO,CAAC,kBAAkB,CAGX;IACf,OAAO,CAAC,iBAAiB,CAAoF;IAE7G;;;OAGG;IACH,YAAY,CACV,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,EAC3B,KAAK,CAAC,EAAE,MAAM,GACb,IAAI;IAWP;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;;OAGG;IACH,YAAY,IAAI;QACd,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;KAC5B,GAAG,IAAI;IAaR;;;;OAIG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IASvC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAI/F;;;;;OAKG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKxC;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkCvE;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAU5B;;OAEG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAM1C;;;;OAIG;IACH,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAI9C;;OAEG;IACH,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIjD;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAUrB;;;;OAIG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxE;;;OAGG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAU5C;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAShC;;;;;;;;;;OAUG;IACG,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAoGvD;;OAEG;YACW,eAAe;IAgG7B;;;OAGG;YACW,WAAW;IAmCzB;;;OAGG;IACH,cAAc,IAAI;QAChB,UAAU,EAAE,OAAO,CAAC;QACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;QAC3B,UAAU,EAAE,OAAO,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,qBAAqB,EAAE,MAAM,EAAE,CAAC;QAChC,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,wBAAwB,EAAE,MAAM,EAAE,CAAC;KACpC;IAgBD;;OAEG;IACH,IAAI,IAAI,IAAI;CA8Bb;AAED,0DAA0D;AAC1D,eAAO,MAAM,SAAS,kBAAyB,CAAC"}