vibepulse 0.2.2 → 0.3.0-beta.0

package/.next/standalone/README.md

@@ -8,23 +8,32 @@ A tiny dashboard that sits in your browser tab — tired of switching IDE tabs j
 
 ## What It Does
 
-- **Kanban board** — Auto-discovers OpenCode sessions, organizes them into Idle / Busy / Review / Done
+- **Kanban board** — Auto-discovers OpenCode sessions and host-global Claude Code sessions, organizes them into Idle / Busy / Review / Done
 - **Remote Nodes** — Connect multiple VibePulse instances to a single hub for a unified view
 - **Audio alerts** — Makes a sound when sessions complete or need attention
 - **Zero setup** — No manual card creation; auto-scans ports and processes
 - **Profile switcher** — Flip between Oh My OpenAgent presets without touching config files
 
+## Claude Code Support
+VibePulse includes experimental, capability-aware support for tracking local [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) sessions:
+- **Host-Global Discovery:** Automatically detects all Claude Code sessions running on the machine, aggregating projects seamlessly.
+- **Explicit Capabilities:** Supported actions are explicitly modeled per provider. Claude now supports VibePulse-managed `archive` and `delete`, while `openEditor` remains disabled until a provider-safe execution path is defined.
+- **Visual Differentiation:** Mixed environments feature distinct visual indicators distinguishing OpenCode and Claude groups inside projects.
+- **Robust Liveness Semantics:** Stale busy states and zombie parsing are prevented at the provider boundary using stricter liveness verification.
+- **Polling Integration:** Claude status updates via polling only locally and remotely. Live SSE streams and real-time event parity are not supported.
+- **Artifact-Backed Child Topology:** Child sessions are exposed only when verified by authoritative artifact-backed linkage. No transcript rendering is supported.
+
 ## Quick Start
 
 ### Hub Mode (Default)
-Run VibePulse locally to monitor your local OpenCode sessions and manage remote nodes.
+Run VibePulse locally to monitor your local sessions and manage remote nodes.
 ```bash
 npx vibepulse
 ```
 Open http://localhost:3456
 
 ### Node Mode
-Run VibePulse on a remote server to expose its OpenCode sessions to a hub.
+Run VibePulse on a remote server to expose its local OpenCode and Claude Code sessions to a hub.
 ```bash
 npx vibepulse --serve
 ```
@@ -43,9 +52,9 @@ Node mode requires an access token for security. See [Architecture](#architectur
 
 ## Architecture
 
-VibePulse uses a Hub-and-Node architecture to aggregate OpenCode sessions across different machines.
+VibePulse uses a Hub-and-Node architecture to aggregate OpenCode and Claude Code sessions across different machines.
 
-1. **Node**: A VibePulse instance running with `--serve`. It interacts directly with the local OpenCode SDK and exposes an API.
+1. **Node**: A VibePulse instance running with `--serve`. It interacts directly with the local OpenCode SDK and Claude Code file-system artifacts and exposes an API.
 2. **Hub**: The primary VibePulse instance (default mode). It connects to one or more Nodes to collect session data.
 
 ### Connecting a Remote Node
@@ -64,6 +73,21 @@ npm install
 npm run dev
 ```
 
+### Claude Integration Verification
+If modifying Claude Code integration, run the targeted regression matrix to ensure discovery order, bounded idle fallback, capability alignment, artifact-backed child topology, stronger liveness semantics, and mixed Claude/OpenCode visual behavior all stay intact:
+
+| Area | Command |
+|------|---------|
+| Claude discovery + topology rules | `npm run test:run -- src/lib/session-providers/claudeCode.test.ts` |
+| Capability alignment + rejection | `npm run test:run -- src/lib/session-providers/providerIds.test.ts src/app/api/sessions/route.test.ts` |
+| Mixed project-group visual behavior | `npm run test:run -- src/components/ProjectCard.test.tsx src/components/SessionCard.test.tsx` |
+| Local provider aggregation and route wiring | `npm run test:run -- src/lib/transform.test.ts src/hooks/useOpencodeSync.test.ts src/app/api/node/sessions/route.test.ts` |
+
+```bash
+npm run test:run -- src/lib/session-providers/providerIds.test.ts src/lib/session-providers/claudeCode.test.ts src/components/ProjectCard.test.tsx src/components/SessionCard.test.tsx src/app/api/sessions/route.test.ts src/app/api/node/sessions/route.test.ts src/lib/transform.test.ts src/hooks/useOpencodeSync.test.ts
+npm run lint && npm run build
+```
+
 ## Tech Stack
 
 - Next.js (App Router) + TypeScript

package/.next/standalone/docs/session-status-detection.md

@@ -158,6 +158,42 @@ sequenceDiagram
 
 ---
 
+## Claude Code Support Boundary
+
+VibePulse includes experimental host-global discovery for Claude Code sessions (`provider = 'claude-code'`). The detection mechanisms used for OpenCode differ for Claude Code due to its specific provider boundaries:
+
+- **Host-Global Discovery:** Uses file-system artifacts (`~/.claude/projects/`, `~/.claude/sessions/`) across the entire host to automatically detect active projects without requiring current-repo constraints.
+- **Artifact-Backed Child Topology:** Nested child sessions are fully supported via local polling and remote node-payload propagation. They roll up naturally into parent card logic. This topology relies entirely on explicit artifact-backed relationships—preventing "guessed" relationships.
+- **Polling Isolation & No SSE Parity:** Claude status updates, including child topology, work via polling only. There is no Claude SSE stream, and therefore no event-level parity with OpenCode's real-time channels.
+- **Robust Stale-Busy Mitigation:**
+  - Status inference uses explicit liveness checks (pid polling/verification) at the provider boundary to ensure zombie processes do not stall the UI in a "busy" state.
+  - Active pid mapping yields `realTimeStatus = 'busy'`.
+  - Artifact-only fallback with dead pids maps to `realTimeStatus = 'idle'`.
+  - Claude never emits `retry`, but it can emit `waitingForUser = true` when fresh transcript evidence shows either a direct assistant question or a pending `tool_use` approval with no later user/tool_result resolution.
+- **Capability-Aware Contracts:** Claude sessions have discrete capability scopes. Claude now supports VibePulse-managed `archive` and `delete`, while `open-editor` remains explicitly disabled until a provider-safe execution path is available.
+
+### Claude "Waiting for User" Decision Rules (Detailed)
+
+Claude detection is transcript-tail based and event-order sensitive:
+
+1. **Freshness gate**
+   - If the transcript artifact is older than the waiting window (currently 10 minutes), `waitingForUser = false`.
+2. **Scan from newest to oldest event**
+   - If the first relevant newest event is a **user** turn, `waitingForUser = false`.
+   - If the first relevant newest event is an **assistant** turn:
+     - `stop_reason === tool_use` or message content contains `tool_use` → `waitingForUser = true`
+     - `stop_reason === end_turn` and assistant text ends with `?` / `？` → `waitingForUser = true`
+     - otherwise → `waitingForUser = false`
+3. **Restore suppression**
+   - Immediately after restore, stale waiting signals can be suppressed until new transcript activity appears.
+
+Practical implication for board status:
+
+- Claude can be `realTimeStatus = idle` **and** `waitingForUser = true` at the same time.
+- In that case, Kanban maps the session to `review` ("Needs Attention") by design, because the session is waiting for user input/approval rather than actively running.
+
+---
+
 ## Detection Limitations (Shortcomings)
 
 ### Root Cause: Unreliable Signal Source

package/.next/standalone/docs/superpowers/specs/2026-04-09-claude-capability-alignment-design.md

@@ -0,0 +1,39 @@
+# Claude Capability Alignment Design
+
+## Goal
+Align Claude Code and OpenCode capabilities in VibePulse through an explicit capability matrix. We also need to fix stale busy status prediction and clearly differentiate providers in the UI.
+
+## Context
+VibePulse recently added global Claude discovery alongside read-only Claude cards. The footer open state is now restored. We still have a known stale-busy problem rooted in weak process ID validation. Current documentation describes Claude as read-only with no action parity. This specification defines the next expansion iteration to replace blunt read-only gating with specific capability flags.
+
+## Non-goals
+We won't build full feature parity for Claude if the underlying CLI lacks support. We also won't rewrite the core Next.js aggregation engine.
+
+## Architecture
+The architecture relies on our existing separation of concerns. Provider contracts live in `src/lib/session-providers/*` and `src/types/index.ts`. Transformation logic resides in `src/lib/transform.ts`. UI action gating happens in `src/components/ProjectCard.tsx`, `src/components/SessionCard.tsx`, and `src/components/KanbanBoard.tsx`. Action routes remain in `src/app/api/sessions/[id]/*`. Implementation is strictly scoped to these boundaries.
+
+## Capability Model
+We replace `readOnly` as our sole capability proxy with explicit action capabilities. A new capability matrix covers `openProject`, `openEditor`, `archive`, and `delete`. We keep the `readOnly` flag but narrow its meaning to indicate basic UI protection.
+
+Current evidence shows Claude archive and delete official support is unclear. The capability matrix must allow staged enablement. We won't pretend parity exists. If Claude cannot safely archive a workspace, the matrix explicitly sets `archive: false`.
+
+## Status Model
+The busy status fix lives at the Claude provider boundary instead of being patched in the UI. When liveness evidence is weak, we prefer false-idle over false-busy for Claude. This specific logic prevents sessions from getting stuck in a busy state when the underlying process might actually be dead or sleeping.
+
+## UI Design
+Visual differentiation uses a mixed strategy. The interface will show a project-level primary provider identity. Individual session rows receive a lightweight indicator. Projects with sessions from multiple providers get explicit mixed-group treatment to avoid user confusion.
+
+## API and Route Enforcement
+Action routes in `src/app/api/sessions/[id]/*` must check the capability matrix before executing destructive actions. If a provider lacks the `archive` capability, the API must reject the request and return a clear error code.
+
+## Testing Strategy
+Tests will verify correct capability matrix enforcement in both UI components and API routes. We will add unit tests for the Claude provider status logic. This ensures the false-idle fallback works correctly under weak liveness conditions.
+
+## Rollout Order
+1. Provider contracts and status logic
+2. UI action gating and visual differentiation
+3. API action-route guards
+4. Tests and documentation
+
+## Risks
+Staged capabilities might frustrate users if missing actions are not explained clearly in the UI. The strict idle fallback could mask active processes if PID checks fail due to obscure OS-level permission boundaries.

package/.next/standalone/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "vibepulse",
-  "version": "0.2.2",
+  "version": "0.3.0-beta.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "vibepulse",
-      "version": "0.2.2",
+      "version": "0.3.0-beta.0",
       "dependencies": {
         "@dnd-kit/core": "^6.3.1",
         "@dnd-kit/sortable": "^10.0.0",

package/.next/standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibepulse",
-  "version": "0.2.2",
+  "version": "0.3.0-beta.0",
   "private": false,
   "description": "Real-time dashboard for monitoring and managing OpenCode sessions",
   "repository": {

package/.next/standalone/src/app/api/node/sessions/[id]/archive/route.test.ts

@@ -5,16 +5,28 @@ vi.mock('@/lib/opencodeDiscovery', () => ({
 }));
 
 vi.mock('@/lib/sessionArchiveOverrides', () => ({
+  clearSessionStickyStatusBlocked: vi.fn(),
   clearSessionForceUnarchived: vi.fn(),
+  markSessionForceUnarchived: vi.fn(),
   markSessionStickyStatusBlocked: vi.fn(),
 }));
 
 import { discoverOpencodePortsWithMeta } from '@/lib/opencodeDiscovery';
 import { createNodeRequestHeaders } from '@/lib/nodeProtocol';
+import {
+  clearSessionStickyStatusBlocked,
+  clearSessionForceUnarchived,
+  markSessionForceUnarchived,
+  markSessionStickyStatusBlocked,
+} from '@/lib/sessionArchiveOverrides';
 
-import { POST } from './route';
+import { DELETE, POST } from './route';
 
 const mockDiscoverOpencodePortsWithMeta: any = discoverOpencodePortsWithMeta;
+const mockClearSessionStickyStatusBlocked: any = clearSessionStickyStatusBlocked;
+const mockClearSessionForceUnarchived: any = clearSessionForceUnarchived;
+const mockMarkSessionForceUnarchived: any = markSessionForceUnarchived;
+const mockMarkSessionStickyStatusBlocked: any = markSessionStickyStatusBlocked;
 
 describe('/api/node/sessions/[id]/archive', () => {
   const originalRuntimeRole = process.env.VIBEPULSE_RUNTIME_ROLE;
@@ -52,6 +64,53 @@ describe('/api/node/sessions/[id]/archive', () => {
       'http://localhost:7777/session/ses_123',
       expect.objectContaining({ method: 'PATCH' })
     );
+    expect(mockClearSessionForceUnarchived).toHaveBeenCalledWith('ses_123');
+    expect(mockMarkSessionStickyStatusBlocked).toHaveBeenCalledWith('ses_123');
+  });
+
+  it('restores a node-local session with valid auth', async () => {
+    const response = await DELETE(
+      new Request('http://localhost/api/node/sessions/ses_123/archive', {
+        method: 'DELETE',
+        headers: createNodeRequestHeaders('shared-secret'),
+      }),
+      { params: Promise.resolve({ id: 'ses_123' }) }
+    );
+    const data = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(data).toEqual({ success: true });
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      'http://localhost:7777/session/ses_123',
+      expect.objectContaining({ method: 'PATCH', body: JSON.stringify({ time: { archived: null } }) })
+    );
+    expect(mockMarkSessionForceUnarchived).toHaveBeenCalledWith('ses_123');
+    expect(mockClearSessionStickyStatusBlocked).toHaveBeenCalledWith('ses_123');
+  });
+
+  it('does not mutate restore overrides when upstream restore fails', async () => {
+    Object.defineProperty(globalThis, 'fetch', {
+      value: vi.fn(async () => new Response(JSON.stringify({ error: 'boom' }), { status: 500 })),
+      configurable: true,
+    });
+
+    const response = await DELETE(
+      new Request('http://localhost/api/node/sessions/ses_123/archive', {
+        method: 'DELETE',
+        headers: createNodeRequestHeaders('shared-secret'),
+      }),
+      { params: Promise.resolve({ id: 'ses_123' }) }
+    );
+    const data = await response.json();
+
+    expect(response.status).toBe(500);
+    expect(data).toEqual({
+      error: 'Failed to restore session',
+      reason: 'node_request_failed_500',
+      message: JSON.stringify({ error: 'boom' }),
+    });
+    expect(mockMarkSessionForceUnarchived).not.toHaveBeenCalled();
+    expect(mockClearSessionStickyStatusBlocked).not.toHaveBeenCalled();
   });
 
   it('rejects invalid auth before mutating', async () => {

package/.next/standalone/src/app/api/node/sessions/[id]/archive/route.ts

@@ -5,7 +5,9 @@ import {
   toNodeRequestGuardResponse,
 } from '@/lib/nodeProtocol';
 import {
+  clearSessionStickyStatusBlocked,
   clearSessionForceUnarchived,
+  markSessionForceUnarchived,
   markSessionStickyStatusBlocked,
 } from '@/lib/sessionArchiveOverrides';
 
@@ -20,28 +22,34 @@ function resolveNodeLocalSessionId(id: string): string | null {
 
 export const dynamic = 'force-dynamic';
 
-export async function POST(request: Request, { params }: { params: Promise<{ id: string }> }) {
-  const guardResult = guardNodeRequest(request);
-  if (!guardResult.ok) {
-    return toNodeRequestGuardResponse(guardResult);
-  }
-
-  const { id } = await params;
-  const sessionId = resolveNodeLocalSessionId(id);
+function createInvalidNodeSessionIdResponse() {
+  return Response.json({ error: 'Invalid node session id' }, { status: 400 });
+}
 
-  if (!sessionId) {
-    return Response.json({ error: 'Invalid node session id' }, { status: 400 });
-  }
+function createNodeUpstreamUnavailableResponse(timedOut: boolean) {
+  return createNodeFailureResponse(timedOut ? 'upstream_timeout' : 'upstream_unreachable', {
+    role: 'node',
+    upstream: {
+      kind: 'opencode',
+      reachable: false,
+    },
+  });
+}
 
+async function runArchiveMutation({
+  sessionId,
+  archived,
+  failureMessage,
+  onSuccess,
+}: {
+  sessionId: string;
+  archived: number | null;
+  failureMessage: string;
+  onSuccess: () => void;
+}): Promise<Response> {
   const { ports, timedOut } = discoverOpencodePortsWithMeta();
   if (!ports.length) {
-    return createNodeFailureResponse(timedOut ? 'upstream_timeout' : 'upstream_unreachable', {
-      role: 'node',
-      upstream: {
-        kind: 'opencode',
-        reachable: false,
-      },
-    });
+    return createNodeUpstreamUnavailableResponse(timedOut);
   }
 
   let sawNotFound = false;
@@ -55,12 +63,11 @@ export async function POST(request: Request, { params }: { params: Promise<{ id:
         headers: {
           'Content-Type': 'application/json',
         },
-        body: JSON.stringify({ time: { archived: Date.now() } }),
+        body: JSON.stringify({ time: { archived } }),
       });
 
       if (response.ok) {
-        clearSessionForceUnarchived(sessionId);
-        markSessionStickyStatusBlocked(sessionId);
+        onSuccess();
         return Response.json({ success: true });
       }
 
@@ -81,7 +88,7 @@ export async function POST(request: Request, { params }: { params: Promise<{ id:
   if (lastFailureStatus !== null) {
     return Response.json(
       {
-        error: 'Failed to archive session',
+        error: failureMessage,
         reason: lastFailureStatus === 503 ? 'upstream_unreachable' : `node_request_failed_${lastFailureStatus}`,
         ...(lastFailureMessage ? { message: lastFailureMessage } : {}),
       },
@@ -95,3 +102,51 @@ export async function POST(request: Request, { params }: { params: Promise<{ id:
 
   return Response.json({ error: 'Session not found', reason: 'session_not_found' }, { status: 404 });
 }
+
+export async function POST(request: Request, { params }: { params: Promise<{ id: string }> }) {
+  const guardResult = guardNodeRequest(request);
+  if (!guardResult.ok) {
+    return toNodeRequestGuardResponse(guardResult);
+  }
+
+  const { id } = await params;
+  const sessionId = resolveNodeLocalSessionId(id);
+
+  if (!sessionId) {
+    return createInvalidNodeSessionIdResponse();
+  }
+
+  return runArchiveMutation({
+    sessionId,
+    archived: Date.now(),
+    failureMessage: 'Failed to archive session',
+    onSuccess: () => {
+      clearSessionForceUnarchived(sessionId);
+      markSessionStickyStatusBlocked(sessionId);
+    },
+  });
+}
+
+export async function DELETE(request: Request, { params }: { params: Promise<{ id: string }> }) {
+  const guardResult = guardNodeRequest(request);
+  if (!guardResult.ok) {
+    return toNodeRequestGuardResponse(guardResult);
+  }
+
+  const { id } = await params;
+  const sessionId = resolveNodeLocalSessionId(id);
+
+  if (!sessionId) {
+    return createInvalidNodeSessionIdResponse();
+  }
+
+  return runArchiveMutation({
+    sessionId,
+    archived: null,
+    failureMessage: 'Failed to restore session',
+    onSuccess: () => {
+      markSessionForceUnarchived(sessionId);
+      clearSessionStickyStatusBlocked(sessionId);
+    },
+  });
+}