@cloudcli-ai/cloudcli 1.37.2 → 1.37.4

package/server/modules/providers/tests/provider-token-usage.service.test.ts

@@ -6,7 +6,10 @@ import test from 'node:test';
 
 import Database from 'better-sqlite3';
 
-import { createProviderTokenUsageService } from '@/modules/providers/services/provider-token-usage.service.js';
+import {
+  createProviderTokenUsageService,
+  summarizeClaudeTokenUsage,
+} from '@/modules/providers/services/provider-token-usage.service.js';
 import { AppError } from '@/shared/utils.js';
 
 function createSessionRow(overrides: Record<string, unknown> = {}) {
@@ -19,6 +22,7 @@ function createSessionRow(overrides: Record<string, unknown> = {}) {
     custom_name: null,
     model: null,
     effort: null,
+    forked_from_session_id: null,
     isArchived: 0,
     created_at: '2026-01-01T00:00:00.000Z',
     updated_at: '2026-01-01T00:00:00.000Z',
@@ -184,3 +188,186 @@ test('token usage reports SESSION_NOT_FOUND for an unknown app session id', asyn
     ),
   );
 });
+
+test('the Claude summarizer reads the newest assistant turn, not the whole conversation', () => {
+  const entries = [
+    { type: 'assistant', message: { usage: { input_tokens: 5, cache_read_input_tokens: 1000, output_tokens: 50 } } },
+    { type: 'user', message: { role: 'user', content: 'next' } },
+    // The newest turn's prompt is the whole context, so its cache_read already
+    // includes everything before it. Summing turns would double-count.
+    { type: 'assistant', message: { usage: { input_tokens: 3, cache_read_input_tokens: 4000, cache_creation_input_tokens: 100, output_tokens: 80 } } },
+  ];
+
+  assert.deepEqual(summarizeClaudeTokenUsage(entries, '200000'), {
+    used: 4183,
+    total: 200_000,
+    inputTokens: 4103,
+    outputTokens: 80,
+    cacheReadTokens: 4000,
+    cacheCreationTokens: 100,
+    cacheTokens: 4100,
+    breakdown: { input: 4103, output: 80 },
+  });
+});
+
+test('the Claude summarizer skips synthetic rows that carry an all-zero usage block', () => {
+  // Interrupts, API errors and "No response requested." are written as
+  // assistant rows with a fully zeroed usage block. Reading one as the newest
+  // turn dropped the composer counter to 0 until the next turn pushed it back.
+  const entries = [
+    { type: 'assistant', message: { usage: { input_tokens: 3, cache_read_input_tokens: 4000, output_tokens: 80 } } },
+    {
+      type: 'assistant',
+      message: {
+        model: '<synthetic>',
+        usage: {
+          input_tokens: 0,
+          output_tokens: 0,
+          cache_creation_input_tokens: 0,
+          cache_read_input_tokens: 0,
+        },
+      },
+    },
+  ];
+
+  assert.equal(summarizeClaudeTokenUsage(entries, '200000').used, 4083);
+});
+
+test('the Claude summarizer skips a subagent sidechain turn', () => {
+  // A sidechain turn reports the subagent's own context window. Reading it
+  // made the counter drop to the subagent's number mid-run.
+  const entries = [
+    { type: 'assistant', message: { usage: { input_tokens: 3, cache_read_input_tokens: 4000, output_tokens: 80 } } },
+    {
+      type: 'assistant',
+      isSidechain: true,
+      message: { usage: { input_tokens: 10, cache_read_input_tokens: 900, output_tokens: 5 } },
+    },
+  ];
+
+  assert.equal(summarizeClaudeTokenUsage(entries, '200000').used, 4083);
+});
+
+test('the Claude summarizer reports zero for a transcript with no assistant turn yet', () => {
+  const usage = summarizeClaudeTokenUsage([{ type: 'user', message: { role: 'user', content: 'hi' } }], '200000');
+
+  assert.equal(usage.used, 0);
+  assert.equal(usage.total, 200_000);
+});
+
+/** Padding rows large enough to push earlier rows out of the 4MB tail window. */
+function paddingLines(totalBytes: number): string {
+  const line = JSON.stringify({ type: 'attachment', filler: 'x'.repeat(4096) });
+  return Array.from({ length: Math.ceil(totalBytes / line.length) }, () => line).join('\n');
+}
+
+test('Claude token usage reads only the tail of a large transcript', async () => {
+  const tempDirectory = await mkdtemp(path.join(tmpdir(), 'provider-token-usage-claude-tail-'));
+  const sessionFilePath = path.join(tempDirectory, 'provider-session.jsonl');
+
+  try {
+    await writeFile(sessionFilePath, [
+      paddingLines(5 * 1024 * 1024),
+      JSON.stringify({ type: 'assistant', message: { usage: { input_tokens: 7, output_tokens: 2 } } }),
+    ].join('\n'));
+
+    const service = createProviderTokenUsageService({
+      getSessionById: () => createSessionRow({ jsonl_path: sessionFilePath }),
+      getClaudeContextWindow: () => '180000',
+      // Reading the whole file here would defeat the tail read; fail loudly.
+      readTextFile: () => { throw new Error('full read must not happen when the tail has usage'); },
+    });
+
+    const usage = await service.getSessionTokenUsage('app-session');
+    assert.equal(usage.inputTokens, 7);
+    assert.equal(usage.outputTokens, 2);
+  } finally {
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+});
+
+test('Claude token usage falls back to the whole file when the tail has no usage row', async () => {
+  const tempDirectory = await mkdtemp(path.join(tmpdir(), 'provider-token-usage-claude-fallback-'));
+  const sessionFilePath = path.join(tempDirectory, 'provider-session.jsonl');
+
+  try {
+    await writeFile(sessionFilePath, [
+      JSON.stringify({ type: 'assistant', message: { usage: { input_tokens: 11, output_tokens: 3 } } }),
+      paddingLines(5 * 1024 * 1024),
+    ].join('\n'));
+
+    const service = createProviderTokenUsageService({
+      getSessionById: () => createSessionRow({ jsonl_path: sessionFilePath }),
+      getClaudeContextWindow: () => '180000',
+    });
+
+    const usage = await service.getSessionTokenUsage('app-session');
+    assert.equal(usage.inputTokens, 11);
+    assert.equal(usage.outputTokens, 3);
+  } finally {
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+});
+
+test('Codex token usage reads only the tail of a large rollout', async () => {
+  const tempDirectory = await mkdtemp(path.join(tmpdir(), 'provider-token-usage-codex-tail-'));
+  const sessionFilePath = path.join(tempDirectory, 'rollout-provider-session.jsonl');
+
+  try {
+    await writeFile(sessionFilePath, [
+      paddingLines(5 * 1024 * 1024),
+      JSON.stringify({
+        type: 'event_msg',
+        payload: {
+          type: 'token_count',
+          info: {
+            total_token_usage: { input_tokens: 21, output_tokens: 8, total_tokens: 29 },
+            model_context_window: 150_000,
+          },
+        },
+      }),
+    ].join('\n'));
+
+    const service = createProviderTokenUsageService({
+      getSessionById: () => createSessionRow({ provider: 'codex', jsonl_path: sessionFilePath }),
+      readTextFile: () => { throw new Error('full read must not happen when the tail has usage'); },
+    });
+
+    assert.deepEqual(await service.getSessionTokenUsage('app-session'), {
+      used: 29,
+      total: 150_000,
+      inputTokens: 21,
+      outputTokens: 8,
+      breakdown: { input: 21, output: 8 },
+    });
+  } finally {
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+});
+
+test('Codex token usage falls back to the whole file when the tail has no token_count row', async () => {
+  const tempDirectory = await mkdtemp(path.join(tmpdir(), 'provider-token-usage-codex-fallback-'));
+  const sessionFilePath = path.join(tempDirectory, 'rollout-provider-session.jsonl');
+
+  try {
+    await writeFile(sessionFilePath, [
+      JSON.stringify({
+        type: 'event_msg',
+        payload: {
+          type: 'token_count',
+          info: { total_token_usage: { input_tokens: 5, output_tokens: 1, total_tokens: 6 } },
+        },
+      }),
+      paddingLines(5 * 1024 * 1024),
+    ].join('\n'));
+
+    const service = createProviderTokenUsageService({
+      getSessionById: () => createSessionRow({ provider: 'codex', jsonl_path: sessionFilePath }),
+    });
+
+    const usage = await service.getSessionTokenUsage('app-session');
+    assert.equal(usage.used, 6);
+  } finally {
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+});

package/server/modules/providers/tests/provider.routes.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { once } from 'node:events';
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import type { AddressInfo } from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
@@ -10,6 +10,9 @@ import express, { type NextFunction, type Request, type Response } from 'express
 
 import { closeConnection, initializeDatabase, sessionsDb } from '@/modules/database/index.js';
 import providerRouter from '@/modules/providers/provider.routes.js';
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import type { IProvider } from '@/shared/interfaces.js';
+import type { BackgroundTaskSummary, WorkflowAgentActivity } from '@/shared/types.js';
 import { AppError } from '@/shared/utils.js';
 
 async function withProviderServer(
@@ -242,3 +245,229 @@ test('model routes expose immutable defaults and full custom model CRUD', async
     );
   });
 });
+
+test('custom model routes accept, validate, and return reasoning-effort levels', async () => {
+  await withProviderServer(async (baseUrl) => {
+    const postModel = async (provider: string, body: unknown) => {
+      const response = await fetch(`${baseUrl}/api/providers/${provider}/models`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+      return {
+        status: response.status,
+        payload: await response.json() as {
+          data?: {
+            model: { recordId: number; effort?: unknown };
+            models: { OPTIONS: Array<{ value: string; effort?: unknown }> };
+          };
+          error?: { code: string; message?: string };
+        },
+      };
+    };
+
+    const created = await postModel('claude', {
+      model: 'My Custom Model',
+      id: 'my-custom-model',
+      effort: { values: [' low ', 'high'], default: 'high' },
+    });
+    const expectedEffort = { default: 'high', values: [{ value: 'low' }, { value: 'high' }] };
+    assert.equal(created.status, 201);
+    assert.deepEqual(created.payload.data?.model.effort, expectedEffort);
+
+    const catalogResponse = await fetch(`${baseUrl}/api/providers/claude/models`);
+    const catalogPayload = await catalogResponse.json() as {
+      data: { models: { OPTIONS: Array<{ value: string; effort?: unknown }>; EFFORT_LEVELS?: string[] } };
+    };
+    assert.deepEqual(
+      catalogPayload.data.models.OPTIONS.find((option) => option.value === 'my-custom-model')?.effort,
+      expectedEffort,
+    );
+    // The model library's toggles come from here, not from the built-in models.
+    assert.deepEqual(
+      catalogPayload.data.models.EFFORT_LEVELS,
+      ['low', 'medium', 'high', 'xhigh', 'max', 'ultracode'],
+    );
+
+    // OpenCode's allowed levels do not depend on which upstream providers the
+    // machine running the tests has connected.
+    const openCodeModel = await postModel('opencode', {
+      model: 'Router model',
+      id: 'openrouter/router-model',
+      effort: { values: ['none', 'high'] },
+    });
+    assert.equal(openCodeModel.status, 201, JSON.stringify(openCodeModel.payload));
+    assert.deepEqual(openCodeModel.payload.data?.model.effort, { values: [{ value: 'none' }, { value: 'high' }] });
+
+    // A PATCH from a client that predates effort metadata keeps the levels.
+    const renameResponse = await fetch(
+      `${baseUrl}/api/providers/claude/models/${created.payload.data?.model.recordId}`,
+      {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ model: 'Renamed', id: 'my-custom-model' }),
+      },
+    );
+    const renamePayload = await renameResponse.json() as { data: { model: { effort?: unknown } } };
+    assert.equal(renameResponse.status, 200);
+    assert.deepEqual(renamePayload.data.model.effort, expectedEffort);
+
+    const invalidPayloads: Array<{ provider: string; effort: unknown; code: string }> = [
+      { provider: 'claude', effort: { values: ['low', 'low'] }, code: 'INVALID_MODEL_EFFORT' },
+      { provider: 'claude', effort: { values: ['low', ''] }, code: 'INVALID_MODEL_EFFORT' },
+      { provider: 'claude', effort: { values: ['low'], default: 'high' }, code: 'INVALID_MODEL_EFFORT' },
+      { provider: 'claude', effort: { values: ['turbo'] }, code: 'INVALID_MODEL_EFFORT' },
+      { provider: 'claude', effort: 'high', code: 'INVALID_MODEL_EFFORT' },
+      { provider: 'cursor', effort: { values: ['low'] }, code: 'MODEL_EFFORT_NOT_SUPPORTED' },
+    ];
+    for (const [index, invalid] of invalidPayloads.entries()) {
+      const rejected = await postModel(invalid.provider, {
+        model: `Invalid ${index}`,
+        id: `invalid-${index}`,
+        effort: invalid.effort,
+      });
+      assert.equal(rejected.status, 400, JSON.stringify(invalid));
+      assert.equal(rejected.payload.error?.code, invalid.code, JSON.stringify(invalid));
+    }
+
+    // An oversized list is refused by its length, before any entry is walked:
+    // the JSON parser accepts bodies of up to 50 MB.
+    const oversized = await postModel('claude', {
+      model: 'Oversized',
+      id: 'oversized',
+      effort: { values: Array.from({ length: 33 }, (_, index) => `level-${index}`) },
+    });
+    assert.equal(oversized.status, 400);
+    assert.equal(oversized.payload.error?.code, 'INVALID_MODEL_EFFORT');
+    assert.match(oversized.payload.error?.message ?? '', /at most 32 effort levels/);
+  });
+});
+
+test('the running-sessions route reports a session held open for background work', async () => {
+  // The client polls this route to keep every tab's activity map in step, so
+  // a session whose turn ended but whose agent is still running has to be in
+  // the payload — flagged as background work, with the tasks to show and stop.
+  const tasks: BackgroundTaskSummary[] = [{
+    taskId: 'a73dc7a6442f7c415',
+    toolUseId: 'toolu_013sUz4iWcNjN6BskVkHUCAr',
+    taskType: 'local_agent',
+    description: 'Investigate the flaky test',
+    startedAt: 1_700_000_000_000,
+  }];
+  const realListProviders = providerRegistry.listProviders;
+  providerRegistry.listProviders = () => [{
+    id: 'claude',
+    runtime: { listBackgroundWork: () => [{ sessionId: 'held-session', tasks }] },
+  } as unknown as IProvider];
+
+  try {
+    await withProviderServer(async (baseUrl) => {
+      const response = await fetch(`${baseUrl}/api/providers/sessions/running`);
+      const payload = await response.json() as { data: { sessions: unknown[] } };
+
+      assert.equal(response.status, 200);
+      assert.deepEqual(payload.data.sessions, [{
+        sessionId: 'held-session',
+        provider: 'claude',
+        startedAt: 1_700_000_000_000,
+        lastSeq: 0,
+        background: true,
+        canInterrupt: false,
+        tasks,
+      }]);
+    });
+  } finally {
+    providerRegistry.listProviders = realListProviders;
+  }
+});
+
+const WORKFLOW_SESSION_ID = 'claude-workflow-routes-session';
+const WORKFLOW_RUN_ID = 'wf_16fbf852-274';
+const FINISHED_AGENT_ID = 'aa1e064cf8bd159d6';
+const UNREPORTED_AGENT_ID = 'ab89f2cde612a51b1';
+
+/**
+ * Writes a workflow run's directory the way a real run leaves it under the
+ * session's transcript directory: one `agent-<id>.jsonl` per agent, in the
+ * row shape an Agent subagent's transcript has, and the journal beside them.
+ */
+async function writeWorkflowRun(projectDirectory: string): Promise<string> {
+  const sessionPath = path.join(projectDirectory, `${WORKFLOW_SESSION_ID}.jsonl`);
+  await mkdir(projectDirectory, { recursive: true });
+  await writeFile(sessionPath, `${JSON.stringify({ type: 'user', uuid: 'u1', sessionId: WORKFLOW_SESSION_ID, timestamp: '2026-08-21T10:32:10.000Z', message: { role: 'user', content: 'audit the frontend' } })}\n`, 'utf8');
+
+  const runDir = path.join(projectDirectory, WORKFLOW_SESSION_ID, 'subagents', 'workflows', WORKFLOW_RUN_ID);
+  await mkdir(runDir, { recursive: true });
+
+  const agentRows = (agentId: string) => [
+    { parentUuid: null, isSidechain: true, agentId, type: 'user', uuid: `${agentId}-u1`, timestamp: '2026-08-21T10:32:20.000Z', message: { role: 'user', content: 'You are the analysis step of a code-quality audit.' } },
+    { parentUuid: `${agentId}-u1`, isSidechain: true, agentId, type: 'assistant', uuid: `${agentId}-a1`, timestamp: '2026-08-21T10:32:25.000Z', message: { role: 'assistant', model: 'claude-opus-4-1', content: [{ type: 'tool_use', id: `toolu_${agentId}_1`, name: 'Grep', input: { pattern: 'useSidebar' } }] } },
+    { parentUuid: `${agentId}-a1`, isSidechain: true, agentId, type: 'user', uuid: `${agentId}-u2`, timestamp: '2026-08-21T10:32:26.000Z', message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: `toolu_${agentId}_1`, content: 'src/modules/sidebar/useSidebar.ts' }] } },
+    { parentUuid: `${agentId}-u2`, isSidechain: true, agentId, type: 'assistant', uuid: `${agentId}-a2`, timestamp: '2026-08-21T10:32:40.000Z', message: { role: 'assistant', model: 'claude-opus-4-1', content: [{ type: 'text', text: 'One hook owns the sidebar.' }] } },
+  ];
+  for (const agentId of [FINISHED_AGENT_ID, UNREPORTED_AGENT_ID]) {
+    await writeFile(path.join(runDir, `agent-${agentId}.jsonl`), `${agentRows(agentId).map((row) => JSON.stringify(row)).join('\n')}\n`, 'utf8');
+    await writeFile(path.join(runDir, `agent-${agentId}.meta.json`), JSON.stringify({ agentType: 'workflow-subagent', spawnDepth: 1 }), 'utf8');
+  }
+  const journal = [
+    { type: 'started', key: 'v2:one', agentId: FINISHED_AGENT_ID, label: 'audit:sidebar', phase: 'Audit' },
+    { type: 'started', key: 'v2:two', agentId: UNREPORTED_AGENT_ID, label: 'synthesize', phase: 'Synthesize' },
+    { type: 'result', key: 'v2:one', agentId: FINISHED_AGENT_ID, result: { area: 'sidebar' } },
+  ];
+  await writeFile(path.join(runDir, 'journal.jsonl'), `${journal.map((row) => JSON.stringify(row)).join('\n')}\n`, 'utf8');
+
+  return sessionPath;
+}
+
+test('the workflow agent route reads an agent\'s timeline and status from its run directory', async () => {
+  await withProviderServer(async (baseUrl, workspacePath) => {
+    const sessionPath = await writeWorkflowRun(workspacePath);
+    const now = new Date().toISOString();
+    sessionsDb.createSession(WORKFLOW_SESSION_ID, 'claude', workspacePath, 'Workflow session', now, now, sessionPath);
+
+    const agentUrl = (runId: string, agentId: string) =>
+      `${baseUrl}/api/providers/sessions/${WORKFLOW_SESSION_ID}/workflows/${runId}/agents/${agentId}`;
+
+    // The SDK streams none of an agent's rows to the parent, so its transcript
+    // is the only record of what it did — read on demand, capped like an
+    // Agent card's, and settled by the journal beside it.
+    const finishedResponse = await fetch(agentUrl(WORKFLOW_RUN_ID, FINISHED_AGENT_ID));
+    const finished = (await finishedResponse.json() as { data: WorkflowAgentActivity }).data;
+    assert.equal(finishedResponse.status, 200);
+    assert.deepEqual(finished.agent, { id: FINISHED_AGENT_ID, label: 'audit:sidebar', model: 'claude-opus-4-1', status: 'completed' });
+    assert.equal(finished.activityCount, 2);
+    assert.deepEqual(finished.activity.map((entry) => entry.kind), ['tool', 'text']);
+    assert.equal(finished.activity[0]?.toolName, 'Grep');
+    assert.deepEqual(finished.activity[0]?.toolInput, { pattern: 'useSidebar' });
+    assert.deepEqual(finished.activity[0]?.toolResult, { content: 'src/modules/sidebar/useSidebar.ts', isError: false });
+    assert.equal(finished.activity[1]?.content, 'One hook owns the sidebar.');
+
+    // A `started` with no `result` or `failed`, and no live run of the session
+    // to still be working in: nothing can report for it any more.
+    const unreportedResponse = await fetch(agentUrl(WORKFLOW_RUN_ID, UNREPORTED_AGENT_ID));
+    const unreported = (await unreportedResponse.json() as { data: WorkflowAgentActivity }).data;
+    assert.equal(unreportedResponse.status, 200);
+    assert.equal(unreported.agent.status, 'stopped');
+    assert.equal(unreported.agent.label, 'synthesize');
+
+    // Both ids name a file under the session directory, so neither may carry
+    // anything but the harness's own shapes — not even a well-formed
+    // directory that happens to exist.
+    for (const [runId, agentId, code] of [
+      [`${WORKFLOW_RUN_ID}%2F..`, FINISHED_AGENT_ID, 'INVALID_WORKFLOW_RUN_ID'],
+      ['subagents', FINISHED_AGENT_ID, 'INVALID_WORKFLOW_RUN_ID'],
+      [WORKFLOW_RUN_ID, '..%2Fjournal', 'INVALID_WORKFLOW_AGENT_ID'],
+      [WORKFLOW_RUN_ID, 'aa1e064cf8bd159d', 'INVALID_WORKFLOW_AGENT_ID'],
+    ] as const) {
+      const response = await fetch(agentUrl(runId, agentId));
+      const payload = await response.json() as { error: { code: string } };
+      assert.equal(response.status, 400, `${runId}/${agentId}`);
+      assert.equal(payload.error.code, code);
+    }
+
+    const missingResponse = await fetch(agentUrl(WORKFLOW_RUN_ID, 'a0000000000000000'));
+    const missing = await missingResponse.json() as { error: { code: string } };
+    assert.equal(missingResponse.status, 404);
+    assert.equal(missing.error.code, 'WORKFLOW_AGENT_NOT_FOUND');
+  });
+});

package/server/modules/providers/tests/session-fork.test.ts

@@ -0,0 +1,173 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { closeConnection, initializeDatabase, sessionsDb } from '@/modules/database/index.js';
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import { sessionsService } from '@/modules/providers/services/sessions.service.js';
+import type { IProviderFork } from '@/shared/interfaces.js';
+
+const SOURCE_ID = 'fork-source';
+
+type ForkCall = {
+  providerSessionId: string;
+  jsonlPath: string;
+  upToAnchorId?: string;
+  title?: string;
+};
+
+async function withForkableClaude(
+  runTest: (context: { calls: ForkCall[]; directory: string }) => Promise<void>,
+  options: { disableFork?: boolean } = {},
+): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const directory = await mkdtemp(path.join(os.tmpdir(), 'session-fork-'));
+  const sourcePath = path.join(directory, 'native-source.jsonl');
+  const forkedPath = path.join(directory, 'native-fork.jsonl');
+  await writeFile(sourcePath, '{}\n', 'utf8');
+  await writeFile(forkedPath, '{}\n', 'utf8');
+
+  closeConnection();
+  process.env.DATABASE_PATH = path.join(directory, 'auth.db');
+  await initializeDatabase();
+
+  const calls: ForkCall[] = [];
+  const claude = providerRegistry.resolveProvider('claude') as { fork?: IProviderFork };
+  const realFork = claude.fork;
+  const replacement = options.disableFork
+    ? undefined
+    : {
+      forkSession: async (input: ForkCall) => {
+        calls.push(input);
+        return { providerSessionId: 'native-fork', jsonlPath: forkedPath };
+      },
+    } as IProviderFork;
+
+  Object.defineProperty(claude, 'fork', { value: replacement, configurable: true, writable: true });
+
+  try {
+    await runTest({ calls, directory });
+  } finally {
+    Object.defineProperty(claude, 'fork', { value: realFork, configurable: true, writable: true });
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+function seedSource(directory: string): void {
+  const now = new Date().toISOString();
+  sessionsDb.createSession(
+    SOURCE_ID,
+    'claude',
+    directory,
+    'Original session',
+    now,
+    now,
+    path.join(directory, 'native-source.jsonl'),
+  );
+  sessionsDb.assignProviderSessionId(SOURCE_ID, 'native-source');
+}
+
+test('a fork becomes an independent session that points back at its source', async () => {
+  await withForkableClaude(async ({ calls, directory }) => {
+    seedSource(directory);
+
+    const result = await sessionsService.forkSessionById(SOURCE_ID, { upToAnchorId: 'uuid-3' });
+
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].providerSessionId, 'native-source');
+    assert.equal(calls[0].upToAnchorId, 'uuid-3');
+
+    const forked = sessionsDb.getSessionById(result.sessionId);
+    assert.ok(forked);
+    // Written before the watcher can see the new file, so it is never indexed
+    // a second time under its provider-native id.
+    assert.equal(forked?.provider_session_id, 'native-fork');
+    assert.equal(forked?.jsonl_path, path.join(directory, 'native-fork.jsonl'));
+    assert.equal(forked?.forked_from_session_id, SOURCE_ID);
+    assert.equal(forked?.custom_name, 'Original session (fork)');
+
+    // The source is untouched: this is "try two approaches", not a move.
+    const source = sessionsDb.getSessionById(SOURCE_ID);
+    assert.equal(source?.provider_session_id, 'native-source');
+    assert.equal(source?.custom_name, 'Original session');
+  });
+});
+
+test('a fork inherits the model and effort of the conversation it branched from', async () => {
+  await withForkableClaude(async ({ directory }) => {
+    seedSource(directory);
+    sessionsDb.setSessionModel(SOURCE_ID, 'claude-opus-5');
+    sessionsDb.setSessionEffort(SOURCE_ID, 'xhigh');
+
+    const result = await sessionsService.forkSessionById(SOURCE_ID);
+
+    const forked = sessionsDb.getSessionById(result.sessionId);
+    assert.equal(forked?.model, 'claude-opus-5');
+    assert.equal(forked?.effort, 'xhigh');
+  });
+});
+
+test('forking replaces a row the watcher already made for the new transcript', async () => {
+  await withForkableClaude(async ({ directory }) => {
+    seedSource(directory);
+    // The watcher wins the race and indexes the fork under its native id.
+    const now = new Date().toISOString();
+    sessionsDb.createSession(
+      'native-fork',
+      'claude',
+      directory,
+      'Indexed by the watcher',
+      now,
+      now,
+      path.join(directory, 'native-fork.jsonl'),
+    );
+
+    const result = await sessionsService.forkSessionById(SOURCE_ID);
+
+    assert.equal(sessionsDb.getSessionById('native-fork'), null);
+    assert.equal(sessionsDb.getSessionById(result.sessionId)?.provider_session_id, 'native-fork');
+  });
+});
+
+test('a session with no transcript yet cannot be forked', async () => {
+  await withForkableClaude(async ({ directory }) => {
+    // An app-created session that has never run: no provider id, no transcript.
+    sessionsDb.createAppSession('never-ran', 'claude', directory, 'Never ran');
+
+    await assert.rejects(
+      () => sessionsService.forkSessionById('never-ran'),
+      (error: Error & { code?: string }) => error.code === 'FORK_SOURCE_NOT_READY',
+    );
+  });
+});
+
+test('a provider without the capability is refused rather than silently ignored', async () => {
+  await withForkableClaude(
+    async ({ directory }) => {
+      seedSource(directory);
+
+      await assert.rejects(
+        () => sessionsService.forkSessionById(SOURCE_ID),
+        (error: Error & { code?: string }) => error.code === 'FORK_NOT_SUPPORTED',
+      );
+    },
+    { disableFork: true },
+  );
+});
+
+test('forking a session that does not exist is a 404', async () => {
+  await withForkableClaude(async () => {
+    await assert.rejects(
+      () => sessionsService.forkSessionById('no-such-session'),
+      (error: Error & { code?: string }) => error.code === 'SESSION_NOT_FOUND',
+    );
+  });
+});