vibepulse 0.2.2 → 0.3.0-beta.0

package/.next/standalone/src/app/api/node/sessions/route.test.ts

@@ -13,6 +13,12 @@ vi.mock('@/lib/opencodeConfig', () => ({
   readConfig: vi.fn(),
 }));
 
+vi.mock('@/lib/session-providers/claudeCode', () => ({
+  claudeCodeLocalSessionProvider: {
+    getSessionsResult: vi.fn(),
+  },
+}));
+
 vi.mock('child_process', async () => {
   const execSync = vi.fn();
   return {
@@ -39,6 +45,7 @@ import {
   discoverOpencodeProcessCwdsWithoutPortWithMeta,
 } from '@/lib/opencodeDiscovery';
 import { readConfig } from '@/lib/opencodeConfig';
+import { claudeCodeLocalSessionProvider } from '@/lib/session-providers/claudeCode';
 import { createNodeRequestHeaders } from '@/lib/nodeProtocol';
 
 import { GET } from './route';
@@ -50,6 +57,7 @@ const mockCreateOpencodeClient: any = createOpencodeClient;
 const mockDiscoverPortsWithMeta: any = discoverOpencodePortsWithMeta;
 const mockDiscoverProcessCwdsWithoutPortWithMeta: any = discoverOpencodeProcessCwdsWithoutPortWithMeta;
 const mockReadConfig: any = readConfig;
+const mockClaudeLocalProviderGetSessionsResult: any = claudeCodeLocalSessionProvider.getSessionsResult;
 const mockExecSync: any = execSync;
 
 function resetDefaultClientMock(): void {
@@ -82,6 +90,13 @@ function createNeverResolvingPromise<T>(signal?: AbortSignal): Promise<T> {
 
 function setupLocalSessionsMocks(): void {
   resetDefaultClientMock();
+  mockClaudeLocalProviderGetSessionsResult.mockResolvedValue({
+    payload: {
+      sessions: [],
+      processHints: [],
+    },
+    sourceMeta: { online: false },
+  });
 
   mockReadConfig.mockResolvedValue({
     vibepulse: {
@@ -225,9 +240,276 @@ describe('/api/node/sessions', () => {
       waitingForUser: true,
     });
     expect(JSON.stringify(data).includes('baseUrl')).toBe(false);
+    expect(data.sessions.every((session: any) => session.hostId === 'local')).toBe(true);
+    expect(data.sessions.every((session: any) => !session.baseUrl)).toBe(true);
     expect(mockCreateOpencodeClient.mock.calls).toEqual([[{ baseUrl: 'http://localhost:7777' }]]);
   });
 
+  it('carries nested Claude child topology in node polling payloads with provider-aware local ids', async () => {
+    mockClaudeLocalProviderGetSessionsResult.mockResolvedValue({
+      payload: {
+        sessions: [
+          {
+            id: 'claude~550e8400-e29b-41d4-a716-446655440000',
+            slug: '550e8400-e29b-41d4-a716-446655440000',
+            title: 'Claude Parent',
+            directory: '/repo/project-one',
+            projectName: 'project-one',
+            branch: 'main',
+            provider: 'claude-code',
+            providerRawId: '550e8400-e29b-41d4-a716-446655440000',
+            rawSessionId: '550e8400-e29b-41d4-a716-446655440000',
+            topology: { childSessions: 'authoritative' },
+            readOnly: true,
+            realTimeStatus: 'busy',
+            waitingForUser: false,
+            children: [
+              {
+                id: '660e8400-e29b-41d4-a716-446655440000',
+                parentID: '550e8400-e29b-41d4-a716-446655440000',
+                rawSessionId: '660e8400-e29b-41d4-a716-446655440000',
+                providerRawId: '660e8400-e29b-41d4-a716-446655440000',
+                title: 'Claude Child',
+                directory: '/repo/project-one',
+                realTimeStatus: 'busy',
+                waitingForUser: false,
+                readOnly: true,
+                topology: { childSessions: 'authoritative' },
+                time: { created: 2_100, updated: Date.now() - 900 },
+              },
+            ],
+            time: { created: 2_000, updated: Date.now() - 1_000 },
+          },
+        ],
+        processHints: [],
+      },
+      sourceMeta: { online: true },
+    });
+
+    const response = await GET(
+      new Request('http://localhost/api/node/sessions', {
+        headers: createNodeRequestHeaders('shared-secret'),
+      })
+    );
+    const data = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(data.sessions).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ id: 'local:parent-1' }),
+        expect.objectContaining({
+          id: 'local:claude~550e8400-e29b-41d4-a716-446655440000',
+          rawSessionId: '550e8400-e29b-41d4-a716-446655440000',
+          sourceSessionKey: 'local:claude~550e8400-e29b-41d4-a716-446655440000',
+          provider: 'claude-code',
+          providerRawId: '550e8400-e29b-41d4-a716-446655440000',
+          readOnly: true,
+          topology: { childSessions: 'authoritative' },
+          children: [
+            expect.objectContaining({
+              id: 'local:claude~660e8400-e29b-41d4-a716-446655440000',
+              rawSessionId: '660e8400-e29b-41d4-a716-446655440000',
+              sourceSessionKey: 'local:claude~660e8400-e29b-41d4-a716-446655440000',
+              parentID: 'local:claude~550e8400-e29b-41d4-a716-446655440000',
+              provider: 'claude-code',
+              providerRawId: '660e8400-e29b-41d4-a716-446655440000',
+              hostId: 'local',
+              hostLabel: 'Local',
+              hostKind: 'local',
+              readOnly: true,
+              topology: { childSessions: 'authoritative' },
+            }),
+          ],
+        }),
+      ])
+    );
+  });
+
+  it('keeps flat Claude polling payloads backward-compatible when provider metadata is sparse', async () => {
+    mockClaudeLocalProviderGetSessionsResult.mockResolvedValue({
+      payload: {
+        sessions: [
+          {
+            id: 'claude~550e8400-e29b-41d4-a716-446655440000',
+            slug: '550e8400-e29b-41d4-a716-446655440000',
+            title: 'Claude Flat Session',
+            directory: '/repo/project-one',
+            projectName: 'project-one',
+            branch: 'main',
+            realTimeStatus: 'idle',
+            waitingForUser: false,
+            readOnly: true,
+            children: [],
+            time: { created: 3_000, updated: Date.now() - 1_500 },
+          },
+        ],
+        processHints: [],
+      },
+      sourceMeta: { online: true },
+    });
+
+    const response = await GET(
+      new Request('http://localhost/api/node/sessions', {
+        headers: createNodeRequestHeaders('shared-secret'),
+      })
+    );
+    const data = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(data.sessions).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: 'local:claude~550e8400-e29b-41d4-a716-446655440000',
+          rawSessionId: '550e8400-e29b-41d4-a716-446655440000',
+          sourceSessionKey: 'local:claude~550e8400-e29b-41d4-a716-446655440000',
+          provider: 'claude-code',
+          providerRawId: '550e8400-e29b-41d4-a716-446655440000',
+          readOnly: true,
+          children: [],
+        }),
+      ])
+    );
+  });
+
+  it('returns Claude polling sessions when OpenCode ports are absent but Claude provider is available', async () => {
+    mockDiscoverProcessCwdsWithoutPortWithMeta.mockReturnValue({
+      processes: [],
+      timedOut: false,
+    });
+    mockDiscoverPortsWithMeta.mockReturnValue({
+      ports: [],
+      timedOut: false,
+    });
+    mockClaudeLocalProviderGetSessionsResult.mockResolvedValue({
+      payload: {
+        sessions: [
+          {
+            id: 'claude~550e8400-e29b-41d4-a716-446655440000',
+            slug: '550e8400-e29b-41d4-a716-446655440000',
+            title: 'Claude Only Session',
+            directory: '/repo/claude-only-project',
+            projectName: 'claude-only-project',
+            branch: 'main',
+            provider: 'claude-code',
+            providerRawId: '550e8400-e29b-41d4-a716-446655440000',
+            rawSessionId: '550e8400-e29b-41d4-a716-446655440000',
+            readOnly: true,
+            topology: { childSessions: 'flat' },
+            realTimeStatus: 'busy',
+            waitingForUser: false,
+            children: [],
+            time: { created: 4_000, updated: Date.now() - 1_000 },
+          },
+        ],
+        processHints: [],
+      },
+      sourceMeta: { online: true },
+    });
+
+    const response = await GET(
+      new Request('http://localhost/api/node/sessions', {
+        headers: createNodeRequestHeaders('shared-secret'),
+      })
+    );
+    const data = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(data).toMatchObject({
+      ok: true,
+      role: 'node',
+      protocolVersion: '1',
+      source: { hostId: 'local', hostLabel: 'Local', hostKind: 'local' },
+      upstream: { kind: 'opencode', reachable: true },
+      processHints: [],
+      hosts: [{ hostId: 'local', hostLabel: 'Local', hostKind: 'local', online: true }],
+      hostStatuses: [{ hostId: 'local', hostLabel: 'Local', hostKind: 'local', online: true }],
+    });
+    expect(data.sessions).toEqual([
+      expect.objectContaining({
+        id: 'local:claude~550e8400-e29b-41d4-a716-446655440000',
+        rawSessionId: '550e8400-e29b-41d4-a716-446655440000',
+        sourceSessionKey: 'local:claude~550e8400-e29b-41d4-a716-446655440000',
+        provider: 'claude-code',
+        providerRawId: '550e8400-e29b-41d4-a716-446655440000',
+        hostId: 'local',
+        hostLabel: 'Local',
+        hostKind: 'local',
+        readOnly: true,
+        topology: { childSessions: 'flat' },
+        children: [],
+      }),
+    ]);
+    expect(mockCreateOpencodeClient).not.toHaveBeenCalled();
+  });
+
+  it('returns degraded Claude fallback sessions when all discovered OpenCode ports fail', async () => {
+    setupLocalSessionsMocks();
+    mockDiscoverPortsWithMeta.mockReturnValue({
+      ports: [7777, 7778],
+      timedOut: false,
+    });
+    mockSessionList.mockRejectedValue(new Error('ECONNREFUSED'));
+    mockClaudeLocalProviderGetSessionsResult.mockResolvedValue({
+      payload: {
+        sessions: [
+          {
+            id: 'claude~550e8400-e29b-41d4-a716-446655440000',
+            slug: '550e8400-e29b-41d4-a716-446655440000',
+            title: 'Claude Fallback Session',
+            directory: '/repo/claude-fallback',
+            projectName: 'claude-fallback',
+            branch: 'main',
+            provider: 'claude-code',
+            providerRawId: '550e8400-e29b-41d4-a716-446655440000',
+            rawSessionId: '550e8400-e29b-41d4-a716-446655440000',
+            readOnly: true,
+            topology: { childSessions: 'flat' },
+            realTimeStatus: 'busy',
+            waitingForUser: false,
+            children: [],
+            time: { created: 5_000, updated: Date.now() - 1_000 },
+          },
+        ],
+        processHints: [],
+      },
+      sourceMeta: { online: true },
+    });
+
+    const response = await GET(
+      new Request('http://localhost/api/node/sessions', {
+        headers: createNodeRequestHeaders('shared-secret'),
+      })
+    );
+    const data = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(data.degraded).toBe(true);
+    expect(data.failedPorts).toEqual([
+      expect.objectContaining({ port: 7777 }),
+      expect.objectContaining({ port: 7778 }),
+    ]);
+    expect(data.sessions).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: 'local:claude~550e8400-e29b-41d4-a716-446655440000',
+          provider: 'claude-code',
+          sourceSessionKey: 'local:claude~550e8400-e29b-41d4-a716-446655440000',
+        }),
+      ])
+    );
+    expect(data.hostStatuses).toEqual([
+      expect.objectContaining({
+        hostId: 'local',
+        online: true,
+        degraded: true,
+      }),
+    ]);
+    expect(mockCreateOpencodeClient.mock.calls).toEqual([
+      [{ baseUrl: 'http://localhost:7777' }],
+      [{ baseUrl: 'http://localhost:7778' }],
+    ]);
+  });
+
   it('rejects unauthenticated requests before running discovery', async () => {
     const response = await GET(
       new Request('http://localhost/api/node/sessions', {

package/.next/standalone/src/app/api/node/sessions/route.ts

@@ -6,7 +6,12 @@ import {
   discoverOpencodeProcessCwdsWithoutPortWithMeta,
 } from '@/lib/opencodeDiscovery';
 import { readConfig } from '@/lib/opencodeConfig';
-import { composeSourceKey } from '@/lib/hostIdentity';
+import { claudeCodeLocalSessionProvider } from '@/lib/session-providers/claudeCode';
+import {
+  composeProviderSourceKey,
+  detectProviderFromRawId,
+  extractProviderRawId,
+} from '@/lib/session-providers/providerIds';
 import {
   NODE_PROTOCOL_VERSION,
   createNodeFailureResponse,
@@ -73,9 +78,20 @@ type HostAwareFields = {
   hostId?: typeof LOCAL_SOURCE.hostId;
   hostLabel?: typeof LOCAL_SOURCE.hostLabel;
   hostKind?: typeof LOCAL_SOURCE.hostKind;
+  provider?: 'opencode' | 'claude-code';
+  providerRawId?: string;
   rawSessionId?: string;
   sourceSessionKey?: string;
   readOnly?: boolean;
+  capabilities?: {
+    openProject: boolean;
+    openEditor: boolean;
+    archive: boolean;
+    delete: boolean;
+  };
+  topology?: {
+    childSessions: 'flat' | 'authoritative';
+  };
 };
 
 type ChildEntry = HostAwareFields & {
@@ -557,38 +573,112 @@ function sortChildEntries(children: ChildEntry[]): void {
   });
 }
 
-function addLocalHostMetadataToChildEntry(child: ChildEntry): ChildEntry {
-  const rawSessionId = child.rawSessionId ?? child.id;
-  const sourceSessionKey = composeSourceKey(LOCAL_SOURCE.hostId, rawSessionId);
+function readSupplementalProviderPayload(payload: unknown): Pick<LocalSessionsSuccessPayload, 'sessions' | 'processHints'> {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return { sessions: [], processHints: [] };
+  }
+
+  const record = payload as Record<string, unknown>;
+
+  return {
+    sessions: Array.isArray(record['sessions']) ? (record['sessions'] as EnrichedSession[]) : [],
+    processHints: Array.isArray(record['processHints']) ? (record['processHints'] as ProcessHint[]) : [],
+  };
+}
+
+async function getSupplementalClaudePayload(stickyBusyDelayMs: number): Promise<
+  Pick<LocalSessionsSuccessPayload, 'sessions' | 'processHints'>
+> {
+  try {
+    const result = await claudeCodeLocalSessionProvider.getSessionsResult({ stickyBusyDelayMs });
+    return readSupplementalProviderPayload(result.payload);
+  } catch {
+    return { sessions: [], processHints: [] };
+  }
+}
+
+function composeLocalProviderSourceKey(
+  rawSessionId: string,
+  fields: Pick<HostAwareFields, 'provider' | 'readOnly' | 'capabilities' | 'topology'>
+) {
+  return composeProviderSourceKey(LOCAL_SOURCE.hostId, rawSessionId, {
+    ...(fields.provider ? { provider: fields.provider } : {}),
+    ...(fields.readOnly !== undefined ? { readOnly: fields.readOnly } : {}),
+    ...(fields.capabilities ? { capabilities: fields.capabilities } : {}),
+    ...(fields.topology ? { topology: fields.topology } : {}),
+  });
+}
+
+function addLocalHostMetadataToChildEntry(
+  child: ChildEntry,
+  parentSourceSessionKey?: string,
+  parentProvider?: HostAwareFields['provider']
+): ChildEntry {
+  const rawSessionId = child.rawSessionId ?? extractProviderRawId(child.id);
+  const inferredProvider = child.provider ?? detectProviderFromRawId(child.id);
+  const provider = inferredProvider === 'claude-code' ? inferredProvider : (parentProvider ?? inferredProvider);
+  const sourceKey = composeLocalProviderSourceKey(rawSessionId, {
+    provider,
+    readOnly: child.readOnly,
+    capabilities: child.capabilities,
+    topology: child.topology,
+  });
+  const rawParentId = child.parentID ? extractProviderRawId(child.parentID) : undefined;
+  const sourceParentKey = parentSourceSessionKey
+    ?? (rawParentId
+      ? composeLocalProviderSourceKey(rawParentId, {
+          provider,
+        }).sourceKey
+      : child.parentID);
 
   return {
     ...child,
-    id: sourceSessionKey,
-    parentID: child.parentID ? composeSourceKey(LOCAL_SOURCE.hostId, child.parentID) : child.parentID,
+    id: sourceKey.sourceKey,
+    parentID: sourceParentKey,
     hostId: LOCAL_SOURCE.hostId,
     hostLabel: LOCAL_SOURCE.hostLabel,
     hostKind: LOCAL_SOURCE.hostKind,
     rawSessionId,
-    sourceSessionKey,
-    readOnly: false,
+    sourceSessionKey: sourceKey.sourceKey,
+    provider,
+    providerRawId: child.providerRawId ?? sourceKey.providerRawId,
+    readOnly: child.readOnly ?? sourceKey.readOnly,
+    capabilities: child.capabilities ?? sourceKey.capabilities,
+    topology: child.topology ?? sourceKey.topology,
   };
 }
 
 function addLocalHostMetadataToSession(session: EnrichedSession): EnrichedSession {
-  const rawSessionId = session.rawSessionId ?? session.id;
-  const sourceSessionKey = composeSourceKey(LOCAL_SOURCE.hostId, rawSessionId);
+  const rawSessionId = session.rawSessionId ?? extractProviderRawId(session.id);
+  const provider = session.provider ?? detectProviderFromRawId(session.id);
+  const sourceKey = composeLocalProviderSourceKey(rawSessionId, {
+    provider,
+    readOnly: session.readOnly,
+    capabilities: session.capabilities,
+    topology: session.topology,
+  });
+  const rawParentId = session.parentID ? extractProviderRawId(session.parentID) : undefined;
+  const sourceParentKey = rawParentId
+    ? composeLocalProviderSourceKey(rawParentId, {
+        provider,
+      }).sourceKey
+    : session.parentID;
 
   return {
     ...session,
-    id: sourceSessionKey,
-    parentID: session.parentID ? composeSourceKey(LOCAL_SOURCE.hostId, session.parentID) : session.parentID,
+    id: sourceKey.sourceKey,
+    parentID: sourceParentKey,
     hostId: LOCAL_SOURCE.hostId,
     hostLabel: LOCAL_SOURCE.hostLabel,
     hostKind: LOCAL_SOURCE.hostKind,
     rawSessionId,
-    sourceSessionKey,
-    readOnly: false,
-    children: session.children.map((child) => addLocalHostMetadataToChildEntry(child)),
+    sourceSessionKey: sourceKey.sourceKey,
+    provider,
+    providerRawId: session.providerRawId ?? sourceKey.providerRawId,
+    readOnly: session.readOnly ?? sourceKey.readOnly,
+    capabilities: session.capabilities ?? sourceKey.capabilities,
+    topology: session.topology ?? sourceKey.topology,
+    children: session.children.map((child) => addLocalHostMetadataToChildEntry(child, sourceKey.sourceKey, provider)),
   };
 }
 
@@ -686,6 +776,20 @@ async function getLocalSessionsResult(stickyBusyDelayMs: number): Promise<LocalS
       return createLocalFailureResult('upstream_timeout', processHints);
     }
 
+    const supplementalClaudePayload = await getSupplementalClaudePayload(stickyBusyDelayMs);
+    if (supplementalClaudePayload.sessions.length > 0 || supplementalClaudePayload.processHints.length > 0) {
+      return {
+        ok: true,
+        payload: {
+          sessions: supplementalClaudePayload.sessions,
+          processHints: [...processHints, ...supplementalClaudePayload.processHints],
+        },
+        meta: {
+          online: true,
+        },
+      };
+    }
+
     return createLocalFailureResult('upstream_unreachable', processHints);
   }
 
@@ -771,6 +875,24 @@ async function getLocalSessionsResult(stickyBusyDelayMs: number): Promise<LocalS
     }
 
     if (results.length > 0 && failedPorts.length === results.length) {
+      const supplementalClaudePayload = await getSupplementalClaudePayload(stickyBusyDelayMs);
+      if (supplementalClaudePayload.sessions.length > 0 || supplementalClaudePayload.processHints.length > 0) {
+        return {
+          ok: true,
+          payload: {
+            sessions: supplementalClaudePayload.sessions,
+            processHints: [...processHints, ...supplementalClaudePayload.processHints],
+            failedPorts,
+            degraded: true,
+          },
+          meta: {
+            online: true,
+            degraded: true,
+            reason: resolveFailureReasonFromMessages(failedPorts.map((entry) => entry.reason)),
+          },
+        };
+      }
+
       pruneStickyState(Date.now(), new Set<string>());
       return createLocalFailureResult(resolveFailureReasonFromMessages(failedPorts.map((entry) => entry.reason)), processHints, {
         failedPorts,
@@ -1069,11 +1191,13 @@ async function getLocalSessionsResult(stickyBusyDelayMs: number): Promise<LocalS
 
     const filteredProcessHints = processHints.filter((hint) => !knownDirectories.has(hint.directory));
 
+    const supplementalClaudePayload = await getSupplementalClaudePayload(stickyBusyDelayMs);
+
     return {
       ok: true,
       payload: {
-        sessions: enrichedSessions,
-        processHints: filteredProcessHints,
+        sessions: [...enrichedSessions, ...supplementalClaudePayload.sessions],
+        processHints: [...filteredProcessHints, ...supplementalClaudePayload.processHints],
         ...(failedPorts.length > 0 ? { failedPorts, degraded: true } : {}),
       },
       meta: {

package/.next/standalone/src/app/api/opencode-events/route.test.ts

@@ -493,7 +493,7 @@ describe('/api/opencode-events', () => {
     const reader = response.body?.getReader();
     expect(reader).toBeTruthy();
 
-    const first = await readPayload(reader!);
+    const first = (await readPayload(reader!)) as any;
     expect(first).toEqual({
       type: 'session.status',
       properties: {
@@ -502,6 +502,8 @@ describe('/api/opencode-events', () => {
       },
       timestamp: 100,
     });
+    expect(first.source).toBeUndefined();
+    expect(first.event).toBeUndefined();
 
     await reader!.cancel();
   });

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

@@ -13,13 +13,19 @@ vi.mock('@/lib/sessionArchiveOverrides', () => ({
   markSessionStickyStatusBlocked: vi.fn(),
 }));
 
+vi.mock('@/lib/claudeSessionOverrides', () => ({
+  markClaudeSessionArchived: vi.fn(),
+}));
+
 import { discoverOpencodePortsWithMeta } from '@/lib/opencodeDiscovery';
 import { listNodeRecords } from '@/lib/nodeRegistry';
+import { markClaudeSessionArchived } from '@/lib/claudeSessionOverrides';
 
 import { POST } from './route';
 
 const mockDiscoverPortsWithMeta: any = discoverOpencodePortsWithMeta;
 const mockListNodeRecords: any = listNodeRecords;
+const mockMarkClaudeSessionArchived: any = markClaudeSessionArchived;
 
 describe('/api/sessions/[id]/archive', () => {
   beforeEach(() => {
@@ -40,6 +46,23 @@ describe('/api/sessions/[id]/archive', () => {
     expect(mockFetch).toHaveBeenCalledWith('http://localhost:7777/session/abc', expect.objectContaining({ method: 'PATCH' }));
   });
 
+  it('treats UUID-like local ids without claude namespace as opencode sessions', async () => {
+    const opencodeUuid = '550e8400-e29b-41d4-a716-446655440000';
+    const mockFetch = vi.fn(async () => new Response(JSON.stringify({ error: 'missing' }), { status: 404 }));
+    vi.stubGlobal('fetch', mockFetch);
+
+    const response = await POST(new Request(`http://localhost/api/sessions/local:${opencodeUuid}/archive`, { method: 'POST' }), {
+      params: Promise.resolve({ id: `local:${opencodeUuid}` }),
+    });
+    const data = await response.json();
+
+    expect(response.status).toBe(404);
+    expect(data).toEqual({ error: 'Session not found', reason: 'session_not_found' });
+    expect(mockMarkClaudeSessionArchived).not.toHaveBeenCalled();
+    expect(mockDiscoverPortsWithMeta).toHaveBeenCalled();
+    expect(mockFetch).toHaveBeenCalledWith(`http://localhost:7777/session/${opencodeUuid}`, expect.objectContaining({ method: 'PATCH' }));
+  });
+
   it('forwards remote archive ids to the matching node endpoint', async () => {
     mockListNodeRecords.mockResolvedValue([
       {
@@ -98,6 +121,84 @@ describe('/api/sessions/[id]/archive', () => {
     expect(data).toEqual({ error: 'Session not found', reason: 'session_not_found' });
   });
 
+  it('archives Claude sessions through local override storage before any OpenCode execution', async () => {
+    const mockFetch = vi.fn();
+    vi.stubGlobal('fetch', mockFetch);
+
+    const response = await POST(new Request('http://localhost/api/sessions/local:claude~550e8400-e29b-41d4-a716-446655440000/archive', { method: 'POST' }), {
+      params: Promise.resolve({ id: 'local:claude~550e8400-e29b-41d4-a716-446655440000' }),
+    });
+    const data = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(data).toEqual({ success: true });
+    expect(mockMarkClaudeSessionArchived).toHaveBeenCalledWith('550e8400-e29b-41d4-a716-446655440000');
+    expect(mockDiscoverPortsWithMeta).not.toHaveBeenCalled();
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('archives scoped Claude sidechain sessions through local override storage', async () => {
+    const scopedSessionId = '550e8400-e29b-41d4-a716-446655440000__agent-a123';
+    const mockFetch = vi.fn();
+    vi.stubGlobal('fetch', mockFetch);
+
+    const response = await POST(new Request(`http://localhost/api/sessions/local:${scopedSessionId}/archive`, { method: 'POST' }), {
+      params: Promise.resolve({ id: `local:${scopedSessionId}` }),
+    });
+    const data = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(data).toEqual({ success: true });
+    expect(mockMarkClaudeSessionArchived).toHaveBeenCalledWith(scopedSessionId);
+    expect(mockDiscoverPortsWithMeta).not.toHaveBeenCalled();
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('rejects remote Claude archive requests before local override or node execution', async () => {
+    const mockFetch = vi.fn();
+    vi.stubGlobal('fetch', mockFetch);
+
+    const response = await POST(new Request('http://localhost/api/sessions/node-1:claude~550e8400-e29b-41d4-a716-446655440000/archive', { method: 'POST' }), {
+      params: Promise.resolve({ id: 'node-1:claude~550e8400-e29b-41d4-a716-446655440000' }),
+    });
+    const data = await response.json();
+
+    expect(response.status).toBe(403);
+    expect(data).toEqual({
+      error: 'Session action not supported by provider',
+      reason: 'provider_capability_unsupported',
+      provider: 'claude-code',
+      capability: 'archive',
+    });
+    expect(mockMarkClaudeSessionArchived).not.toHaveBeenCalled();
+    expect(mockListNodeRecords).not.toHaveBeenCalled();
+    expect(mockDiscoverPortsWithMeta).not.toHaveBeenCalled();
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('rejects remote scoped Claude sidechain archive requests before node execution', async () => {
+    const scopedSessionId = '550e8400-e29b-41d4-a716-446655440000__agent-a123';
+    const mockFetch = vi.fn();
+    vi.stubGlobal('fetch', mockFetch);
+
+    const response = await POST(new Request(`http://localhost/api/sessions/node-1:${scopedSessionId}/archive`, { method: 'POST' }), {
+      params: Promise.resolve({ id: `node-1:${scopedSessionId}` }),
+    });
+    const data = await response.json();
+
+    expect(response.status).toBe(403);
+    expect(data).toEqual({
+      error: 'Session action not supported by provider',
+      reason: 'provider_capability_unsupported',
+      provider: 'claude-code',
+      capability: 'archive',
+    });
+    expect(mockMarkClaudeSessionArchived).not.toHaveBeenCalled();
+    expect(mockListNodeRecords).not.toHaveBeenCalled();
+    expect(mockDiscoverPortsWithMeta).not.toHaveBeenCalled();
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
   it('does not misclassify non-404 local archive failures as session_not_found', async () => {
     const mockFetch = vi.fn(async () => new Response(JSON.stringify({ error: 'boom' }), { status: 500 }));
     vi.stubGlobal('fetch', mockFetch);