Polish Coven demo loop

Author: BunsDev

README.md

@@ -105,9 +105,20 @@ comux works as a standalone tmux/worktree cockpit. It also speaks to Coven when
 
 Coven is the harness substrate. comux is the cockpit. OpenMeow and OpenClaw can sit above them as intake and orchestration layers.
 
+Demo loop:
+
+1. Open a project in comux.
+2. Launch a Coven-backed Codex or Claude Code session.
+3. Watch it as a visible pane/session.
+4. Inspect files and diffs.
+5. Merge, create a PR, archive, or clean up explicitly.
+
+See [comux + Coven demo loop](./docs/COVEN-DEMO-LOOP.md) and the [OpenCoven public roadmap](https://github.com/OpenCoven/coven/blob/main/docs/ROADMAP.md).
+
 ## Docs
 
 - [Documentation index](./docs/README.md)
+- [comux + Coven demo loop](./docs/COVEN-DEMO-LOOP.md)
 - [Product spec](./docs/PRODUCT-SPEC.md)
 - [Smoke test](./docs/SMOKE.md)
 - [Contributing](./CONTRIBUTING.md)

__tests__/covenSessions.test.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { describe, expect, it } from 'vitest';
 import {
   filterCovenSessionsForProjectRoots,
+  listCovenSessionsFromDaemon,
   parseCovenSessionsJson,
 } from '../src/utils/covenSessions.js';
 
@@ -51,6 +52,30 @@ describe('coven session adapter', () => {
     expect(sessions.map((session) => session.id)).toEqual(['session-2']);
   });
 
+  it('loads sessions from the current Coven daemon API by default', async () => {
+    const result = await listCovenSessionsFromDaemon({
+      client: {
+        listSessions: async () => [
+          {
+            id: 'session-3',
+            projectRoot: '/repo',
+            harness: 'claude',
+            title: 'Review branch',
+            status: 'running',
+            createdAt: '2026-05-10T08:00:00Z',
+            updatedAt: '2026-05-10T08:01:00Z',
+          },
+        ],
+      },
+    });
+
+    expect(result).toMatchObject({
+      status: 'ready',
+      source: 'coven daemon API',
+      sessions: [{ id: 'session-3', harness: 'claude' }],
+    });
+  });
+
   it('filters sessions to verified comux project roots', async () => {
     const root = await tempDir('comux-coven-root-');
     const child = await tempDir('comux-coven-root-child-');

__tests__/daemon/bridge.test.ts

@@ -243,6 +243,43 @@ describe('daemon bridge Coven helpers', () => {
 });
 
 describe('daemon bridge Coven API client', () => {
+  it('accepts the current Coven daemon v1 health contract without legacy supported versions', async () => {
+    const server = http.createServer((req, res) => {
+      res.setHeader('Content-Type', 'application/json');
+      if (req.url === '/api/v1/health') {
+        res.end(JSON.stringify({
+          ok: true,
+          apiVersion: 'coven.daemon.v1',
+          capabilities: {
+            sessions: true,
+            events: true,
+            eventCursor: 'sequence',
+            structuredErrors: true,
+          },
+          daemon: null,
+        }));
+        return;
+      }
+      if (req.url === '/api/v1/sessions') {
+        res.end(JSON.stringify([]));
+        return;
+      }
+      res.statusCode = 404;
+      res.end(JSON.stringify({ error: { code: 'not_found', message: 'not found' } }));
+    });
+
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+    try {
+      const address = server.address();
+      if (!address || typeof address === 'string') throw new Error('expected TCP server');
+      const client = createCovenClient({ baseUrl: `http://127.0.0.1:${address.port}` });
+
+      await expect(client.listSessions()).resolves.toEqual([]);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
   it('accepts newer daemon API versions when v1 remains supported', async () => {
     const server = http.createServer((req, res) => {
       res.setHeader('Content-Type', 'application/json');
@@ -325,17 +362,17 @@ describe('daemon bridge Coven API client', () => {
     }
   });
 
-  it('requests Coven events after a since cursor when provided', async () => {
+  it('requests Coven events after a sequence cursor when provided', async () => {
     const requests: string[] = [];
     const server = http.createServer((req, res) => {
       requests.push(req.url || '/');
       res.setHeader('Content-Type', 'application/json');
       if (req.url === '/api/v1/health') {
-        res.end(JSON.stringify({ ok: true, apiVersion: 'v1', supportedApiVersions: ['v1'], daemon: null }));
+        res.end(JSON.stringify({ ok: true, apiVersion: 'coven.daemon.v1', capabilities: { eventCursor: 'sequence' }, daemon: null }));
         return;
       }
       if (req.url?.startsWith('/api/v1/events?')) {
-        res.end(JSON.stringify([]));
+        res.end(JSON.stringify({ events: [], nextCursor: null, hasMore: false }));
         return;
       }
       res.statusCode = 404;
@@ -348,12 +385,44 @@ describe('daemon bridge Coven API client', () => {
       if (!address || typeof address === 'string') throw new Error('expected TCP server');
       const client = createCovenClient({ baseUrl: `http://127.0.0.1:${address.port}` });
 
-      await expect(client.listEvents?.('session-1', { since: '2026-05-10T08:00:02Z' })).resolves.toEqual([]);
+      await expect(client.listEvents?.('session-1', { afterSeq: 42 })).resolves.toEqual([]);
     } finally {
       await new Promise<void>((resolve) => server.close(() => resolve()));
     }
 
-    expect(requests).toContain('/api/v1/events?sessionId=session-1&since=2026-05-10T08%3A00%3A02Z');
+    expect(requests).toContain('/api/v1/events?sessionId=session-1&afterSeq=42');
+  });
+
+  it('surfaces structured Coven API errors by code and message', async () => {
+    const server = http.createServer((req, res) => {
+      res.setHeader('Content-Type', 'application/json');
+      if (req.url === '/api/v1/health') {
+        res.end(JSON.stringify({ ok: true, apiVersion: 'coven.daemon.v1', capabilities: { structuredErrors: true }, daemon: null }));
+        return;
+      }
+      res.statusCode = 409;
+      res.end(JSON.stringify({
+        error: {
+          code: 'session_not_live',
+          message: 'Session is not live.',
+          details: { sessionId: 'session-1' },
+        },
+      }));
+    });
+
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+    try {
+      const address = server.address();
+      if (!address || typeof address === 'string') throw new Error('expected TCP server');
+      const client = createCovenClient({ baseUrl: `http://127.0.0.1:${address.port}` });
+
+      await expect(client.getSession?.('session-1')).rejects.toMatchObject({
+        code: 'session_not_live',
+        message: 'Session is not live.',
+      });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
   });
 
   it('retries Coven health after a transient failure', async () => {
@@ -421,15 +490,20 @@ describe('daemon bridge Coven API client', () => {
           return;
         }
         if (req.url === '/api/v1/events?sessionId=session-1') {
-          res.end(JSON.stringify([
-            {
-              id: 'event-1',
-              session_id: 'session-1',
-              kind: 'output',
-              payload_json: '{"data":"hello"}',
-              created_at: '2026-05-10T08:00:02Z',
-            },
-          ]));
+          res.end(JSON.stringify({
+            events: [
+              {
+                seq: 42,
+                id: 'event-1',
+                session_id: 'session-1',
+                kind: 'output',
+                payload_json: '{"data":"hello"}',
+                created_at: '2026-05-10T08:00:02Z',
+              },
+            ],
+            nextCursor: { afterSeq: 42 },
+            hasMore: false,
+          }));
           return;
         }
         if (req.url === '/api/v1/sessions/session-1/input') {
@@ -448,7 +522,7 @@ describe('daemon bridge Coven API client', () => {
       const client = createCovenClient({ baseUrl: `http://127.0.0.1:${address.port}` });
 
       await expect(client.listSessions()).resolves.toMatchObject([{ id: 'session-1', projectRoot: '/repo' }]);
-      await expect(client.listEvents?.('session-1')).resolves.toMatchObject([{ id: 'event-1', sessionId: 'session-1' }]);
+      await expect(client.listEvents?.('session-1')).resolves.toMatchObject([{ seq: 42, id: 'event-1', sessionId: 'session-1' }]);
       await expect(client.sendInput?.('session-1', 'hello')).resolves.toBeUndefined();
     } finally {
       await new Promise<void>((resolve) => server.close(() => resolve()));

__tests__/useCovenDesktopUse.test.ts

@@ -18,7 +18,8 @@ const session: CovenSessionSummary = {
   updatedAt: '2026-05-10T08:00:03Z',
 };
 
-const event = (id: string, createdAt: string): CovenSessionEvent => ({
+const event = (id: string, createdAt: string, seq?: number): CovenSessionEvent => ({
+  seq,
   id,
   sessionId: 'session-1',
   kind: 'tool_result',
@@ -73,7 +74,7 @@ describe('loadCovenDesktopUseStates', () => {
   it('prunes cached session events for desktop-use panes that are no longer active', async () => {
     const cache = createDesktopUseLoadCache();
     cache.eventsBySessionId.set('stale-session', [event('stale-event', '2026-05-10T07:59:00Z')]);
-    cache.sinceBySessionId.set('stale-session', '2026-05-10T07:59:00Z');
+    cache.cursorBySessionId.set('stale-session', { afterSeq: 1 });
 
     const client: Pick<CovenClient, 'getSession' | 'listEvents'> = {
       getSession: vi.fn(async () => session),
@@ -83,29 +84,29 @@ describe('loadCovenDesktopUseStates', () => {
     await loadCovenDesktopUseStates([pane('pane-1')], client, cache);
 
     expect(cache.eventsBySessionId.has('stale-session')).toBe(false);
-    expect(cache.sinceBySessionId.has('stale-session')).toBe(false);
+    expect(cache.cursorBySessionId.has('stale-session')).toBe(false);
     expect(cache.eventsBySessionId.has('session-1')).toBe(true);
   });
 
-  it('uses a since cursor and bounded cached events for subsequent refreshes', async () => {
+  it('uses the Coven event sequence cursor and bounded cached events for subsequent refreshes', async () => {
     const cache = createDesktopUseLoadCache();
-    const calls: Array<{ sessionId: string; since?: string }> = [];
+    const calls: Array<{ sessionId: string; afterSeq?: number }> = [];
     const client: Pick<CovenClient, 'getSession' | 'listEvents'> = {
       getSession: vi.fn(async () => session),
-      listEvents: vi.fn(async (sessionId: string, options?: { since?: string }) => {
-        calls.push({ sessionId, since: options?.since });
+      listEvents: vi.fn(async (sessionId: string, options?: { afterSeq?: number }) => {
+        calls.push({ sessionId, afterSeq: options?.afterSeq });
         return calls.length === 1
-          ? [event('event-1', '2026-05-10T08:00:01Z')]
-          : [event('event-2', '2026-05-10T08:00:02Z')];
+          ? [event('event-1', '2026-05-10T08:00:01Z', 41)]
+          : [event('event-2', '2026-05-10T08:00:02Z', 42)];
       }),
     };
 
     const first = await loadCovenDesktopUseStates([pane('pane-1')], client, cache);
     const second = await loadCovenDesktopUseStates([pane('pane-1')], client, cache);
 
     expect(calls).toEqual([
-      { sessionId: 'session-1', since: undefined },
-      { sessionId: 'session-1', since: '2026-05-10T08:00:01Z' },
+      { sessionId: 'session-1', afterSeq: undefined },
+      { sessionId: 'session-1', afterSeq: 41 },
     ]);
     expect(first.get('pane-1')?.screenshotPath).toBe('/tmp/event-1.png');
     expect(second.get('pane-1')?.actions.map((action) => action.id)).toEqual(['event-2', 'event-1']);

docs/COVEN-DEMO-LOOP.md

@@ -0,0 +1,86 @@
+# comux + Coven demo loop
+
+This loop is the public OpenCoven story in the smallest useful form:
+
+1. Open a project in comux.
+2. Launch or attach a Coven-backed Codex or Claude Code session.
+3. Watch the work as a visible pane/session.
+4. Inspect files and diffs from comux.
+5. Merge, create a PR, archive, or clean up explicitly.
+
+The upstream OpenCoven roadmap tracks this same slice under the comux "Next" milestone:
+https://github.com/OpenCoven/coven/blob/main/docs/ROADMAP.md
+
+## Prerequisites
+
+Install comux and Coven, then verify both from the same shell:
+
+```bash
+npm install -g comux
+npx @opencoven/cli doctor
+```
+
+Coven is optional. comux still works as a standalone tmux/worktree cockpit when Coven is not installed or the daemon is stopped.
+
+For the Coven-backed path, start the local daemon:
+
+```bash
+coven doctor
+coven daemon start
+coven daemon status
+```
+
+## Demo path
+
+From the repository you want to work in:
+
+```bash
+cd /path/to/project
+comux
+```
+
+Inside comux:
+
+1. Press `n` to create a normal comux agent pane, or press `d` to launch the desktop-use Coven pane.
+2. For a CLI-launched Coven session, run one of these in a terminal pane:
+
+   ```bash
+   coven run codex "fix the failing tests" --title "Fix tests"
+   coven run claude "review this branch" --title "Review branch"
+   ```
+
+3. The side panel shows matching Coven sessions for the active project when the daemon API is reachable.
+4. Use `j` to watch the pane, `f` to inspect files and diffs, and `m` to open the pane menu.
+5. Finish with an explicit action: merge, create a GitHub PR, close/archive the session, or clean up the worktree.
+
+## Current Coven contract verified by comux
+
+comux talks to the local Coven daemon through `/api/v1`:
+
+- `GET /api/v1/health`
+- `GET /api/v1/sessions`
+- `POST /api/v1/sessions`
+- `GET /api/v1/sessions/:id`
+- `GET /api/v1/events?sessionId=...`
+- `POST /api/v1/sessions/:id/input`
+
+The current stable daemon contract is `apiVersion: "coven.daemon.v1"`. Event reads use the paginated event envelope with `nextCursor.afterSeq`, and comux keeps polling from that sequence cursor instead of replaying the whole event log.
+
+The older `coven sessions --json` adapter remains available only as an explicit legacy fallback for visibility-only compatibility. The default list, launch, open, and event paths use the local daemon API.
+
+## Unavailable states
+
+If Coven is missing or stopped, comux keeps running:
+
+- the side panel shows a compact Coven unavailable state;
+- desktop-use launch failures point at `coven daemon start`;
+- ordinary comux panes, worktrees, file browsing, merge, PR, and cleanup flows still work.
+
+Use this recovery checklist:
+
+```bash
+command -v coven
+coven doctor
+coven daemon restart
+coven daemon status
+```

docs/COVEN-SESSIONS.md

@@ -1,16 +1,29 @@
 # Coven session visibility
 
-comux treats Coven as an optional local runtime. The first integration slice is deliberately thin: comux can render a read-only Coven sessions section in the side panel when a future `coven sessions --json` command is available.
+comux treats Coven as an optional local runtime. comux stays useful on its own, and when a local Coven daemon is available it can show, launch, and attach Coven-managed sessions beside normal comux panes.
 
 ## Adapter boundary
 
-The TUI calls:
+The preferred bridge path is the local daemon API:
+
+```text
+GET  /api/v1/health
+GET  /api/v1/sessions
+POST /api/v1/sessions
+GET  /api/v1/sessions/:id
+GET  /api/v1/events?sessionId=...
+POST /api/v1/sessions/:id/input
+```
+
+comux first checks `GET /api/v1/health` and accepts the current stable `apiVersion: "coven.daemon.v1"` contract. Event polling accepts the current paginated envelope and stores `nextCursor.afterSeq`-style sequence progress by reading event `seq` values.
+
+The legacy visibility-only CLI fallback is still supported for tests and older local builds when explicitly configured:
 
 ```bash
 coven sessions --json
 ```
 
-If the command is missing, unsupported, invalid JSON, or too slow, comux keeps running and shows a compact unavailable state. No unpublished Coven APIs are imported.
+If the daemon or command is missing, unsupported, invalid JSON, or too slow, comux keeps running and shows a compact unavailable state. No unpublished Coven APIs are imported.
 
 ## Proposed JSON contract
 
@@ -57,5 +70,7 @@ Required fields for comux visibility are `id` and `projectRoot`/`project_root`.
 - Sessions whose project roots cannot be verified are hidden.
 - The side panel renders a small `☾ Coven sessions` section under each project with matching sessions.
 - Empty and unavailable states are non-fatal and stay inside the side panel.
+- Desktop-use panes launch through the daemon API and attach with `coven attach <session-id>`.
+- Socket/daemon failures are reported as action-oriented messages, such as starting Coven with `coven daemon start`.
 
-Future slices can add selection, attach/open actions, and live event timelines without changing this adapter boundary.
+See [comux + Coven demo loop](COVEN-DEMO-LOOP.md) for the end-to-end demo path and the [OpenCoven public roadmap](https://github.com/OpenCoven/coven/blob/main/docs/ROADMAP.md) for the upstream milestone.