@cloudcli-ai/cloudcli 1.37.1 → 1.37.3

package/server/modules/database/schema.ts

@@ -96,6 +96,30 @@ CREATE TABLE IF NOT EXISTS projects (
 );
 `;
 
+export const SCHEDULED_MESSAGES_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS scheduled_messages (
+    id TEXT PRIMARY KEY,
+    user_id INTEGER NOT NULL,
+    session_id TEXT NOT NULL,
+    content TEXT NOT NULL,
+    -- Composer preferences (model, effort, permission mode, attachments) as
+    -- they were when the message was scheduled, so it runs the way the user
+    -- set it up rather than however the session is configured hours later.
+    options TEXT NOT NULL DEFAULT '{}',
+    -- UTC. The client sends an absolute instant so the schedule does not move
+    -- when the user changes time zone between scheduling and firing.
+    scheduled_for DATETIME NOT NULL,
+    -- pending | sent | failed | cancelled
+    status TEXT NOT NULL DEFAULT 'pending',
+    -- Why a failed one failed, shown next to it in the composer.
+    failure_reason TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+    FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+`;
+
 export const SESSIONS_TABLE_SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS sessions (
     session_id TEXT NOT NULL,
@@ -114,6 +138,10 @@ CREATE TABLE IF NOT EXISTS sessions (
     -- restores its exact runtime configuration instead of provider defaults.
     model TEXT,
     effort TEXT,
+    -- The app session this one was branched from, NULL for sessions created
+    -- normally. Informational only: a fork is a fully independent provider
+    -- session, and deleting the source does not affect it.
+    forked_from_session_id TEXT,
     isArchived BOOLEAN DEFAULT 0,
     created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
     updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
@@ -160,6 +188,68 @@ CREATE TABLE IF NOT EXISTS provider_models (
 );
 `;
 
+/**
+ * Per-user application preferences that used to live in browser localStorage.
+ *
+ * One row per (user, key); `preference_value` is always a JSON document so a
+ * key can hold a scalar (`"dark"`), a flag (`false`) or a whole settings blob
+ * without the schema having to know which. Keeping them server-side is what
+ * makes a preference follow the user from one device to another.
+ */
+export const USER_PREFERENCES_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS user_preferences (
+    user_id INTEGER NOT NULL,
+    preference_key TEXT NOT NULL,
+    preference_value TEXT NOT NULL,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (user_id, preference_key),
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+`;
+
+/**
+ * Unsent composer text and queued messages, per user and per chat scope.
+ *
+ * `draft_scope` is a session id, or `project:<projectId>` for a chat that has
+ * not been sent yet and therefore has no session. Storing this server-side is
+ * what lets a message typed on a laptop be finished on a phone.
+ */
+export const SESSION_DRAFTS_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS session_drafts (
+    user_id INTEGER NOT NULL,
+    draft_scope TEXT NOT NULL,
+    draft_text TEXT NOT NULL DEFAULT '',
+    queued_message TEXT,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (user_id, draft_scope),
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+`;
+
+/**
+ * Provider sessions an app session has moved off, and must never move back to.
+ *
+ * Editing a message on a provider that cannot resume a transcript partway
+ * (Codex) is done by branching: the conversation is copied up to the edited
+ * turn and the app session follows the copy. The original transcript is left
+ * on disk untouched — nothing is deleted — but it is no longer the session's,
+ * and the indexer would otherwise rediscover it on its next full scan and hand
+ * the session back to the version the user edited away from.
+ */
+export const SUPERSEDED_PROVIDER_SESSIONS_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS superseded_provider_sessions (
+    provider_session_id TEXT NOT NULL,
+    provider TEXT NOT NULL,
+    session_id TEXT NOT NULL,
+    -- The transcript the session left behind. Recorded because the session row
+    -- stops pointing at it, and "delete this conversation from disk" has to
+    -- reach every file the conversation ever lived in.
+    jsonl_path TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (provider_session_id, provider)
+);
+`;
+
 export const INIT_SCHEMA_SQL = `
 -- Initialize authentication database
 PRAGMA foreign_keys = ON;
@@ -207,4 +297,10 @@ ${APP_CONFIG_TABLE_SCHEMA_SQL}
 ${PROVIDER_MODELS_TABLE_SCHEMA_SQL}
 CREATE INDEX IF NOT EXISTS idx_provider_models_provider_order
 ON provider_models(provider, sort_order, id);
+
+${USER_PREFERENCES_TABLE_SCHEMA_SQL}
+
+${SESSION_DRAFTS_TABLE_SCHEMA_SQL}
+
+${SUPERSEDED_PROVIDER_SESSIONS_TABLE_SCHEMA_SQL}
 `;

package/server/modules/database/tests/sessions.db.integration.test.ts

@@ -72,6 +72,58 @@ test('createSession reactivates archived rows when the session becomes active ag
   });
 });
 
+test("createSession leaves an archived row archived when the transcript has not changed", async () => {
+  await withIsolatedDatabase(() => {
+    const createdAt = "2026-07-18T09:00:00.000Z";
+    const updatedAt = "2026-07-18T10:00:00.000Z";
+    const jsonlPath = "/transcripts/session-untouched.jsonl";
+
+    sessionsDb.createSession("session-untouched", "claude", "/workspace/demo-project", "A Name", createdAt, updatedAt, jsonlPath);
+    sessionsDb.updateSessionIsArchived("session-untouched", true);
+
+    // A full rescan re-indexes every transcript created since the last scan,
+    // changed or not, and hands over the timestamps the file still carries.
+    sessionsDb.createSession("session-untouched", "claude", "/workspace/demo-project", "A Name", createdAt, updatedAt, jsonlPath);
+
+    assert.equal(sessionsDb.getSessionById("session-untouched")?.isArchived, 1);
+    assert.equal(sessionsDb.getArchivedSessions().length, 1);
+    assert.equal(sessionsDb.getAllSessions().length, 0);
+
+    // Actually writing to the session again still brings it back.
+    sessionsDb.createSession("session-untouched", "claude", "/workspace/demo-project", "A Name", createdAt, "2026-07-18T11:00:00.000Z", jsonlPath);
+
+    assert.equal(sessionsDb.getSessionById("session-untouched")?.isArchived, 0);
+  });
+});
+
+test("the upsert path counts an omitted timestamp as activity", async () => {
+  await withIsolatedDatabase(() => {
+    // An app-created row carries no provider id, so indexing it takes the
+    // INSERT ... ON CONFLICT branch rather than the UPDATE above. Its
+    // updated_at is CURRENT_TIMESTAMP, which resolves to whole seconds, so a
+    // call in the same second is not *newer* -- the omitted timestamp itself
+    // has to be what reactivates the row.
+    sessionsDb.createAppSession("session-legacy", "claude", "/workspace/demo-project");
+    sessionsDb.updateSessionIsArchived("session-legacy", true);
+
+    sessionsDb.createSession("session-legacy", "claude", "/workspace/demo-project", "Indexed Name");
+
+    assert.equal(sessionsDb.getSessionById("session-legacy")?.isArchived, 0);
+  });
+});
+
+test("the upsert path leaves an archived row alone for a transcript older than it", async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession("session-stale", "claude", "/workspace/demo-project");
+    sessionsDb.updateSessionIsArchived("session-stale", true);
+
+    sessionsDb.createSession("session-stale", "claude", "/workspace/demo-project", "Indexed Name", "2026-07-18T09:00:00.000Z", "2026-07-18T10:00:00.000Z", "/transcripts/session-stale.jsonl");
+
+    assert.equal(sessionsDb.getSessionById("session-stale")?.isArchived, 1);
+  });
+});
+
+
 test('repository reads normalize SQLite UTC timestamps to ISO strings', async () => {
   await withIsolatedDatabase(() => {
     sessionsDb.createAppSession('session-timezone', 'claude', '/workspace/demo-project');

package/server/modules/database/tests/user-preferences.db.integration.test.ts

@@ -0,0 +1,135 @@
+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,
+  getConnection,
+  initializeDatabase,
+  sessionDraftsDb,
+  userPreferencesDb,
+} from '@/modules/database/index.js';
+
+const USER_ID = 1;
+
+async function withDatabase(runTest: () => void | Promise<void>): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'user-prefs-db-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await writeFile(databasePath, '');
+  await initializeDatabase();
+
+  // Both tables cascade from users(id), so a row has to exist to write against.
+  getConnection()
+    .prepare('INSERT INTO users (id, username, password_hash) VALUES (?, ?, ?)')
+    .run(USER_ID, 'tester', 'hash');
+
+  try {
+    await runTest();
+  } finally {
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+}
+
+test('preferences round-trip every JSON shape a setting can take', async () => {
+  await withDatabase(() => {
+    userPreferencesDb.savePreferences(USER_ID, {
+      theme: 'dark',
+      tasksEnabled: false,
+      claudePermissions: { allowedTools: ['Read'], skipPermissions: true },
+    });
+
+    assert.deepEqual(userPreferencesDb.getPreferences(USER_ID), {
+      theme: 'dark',
+      tasksEnabled: false,
+      claudePermissions: { allowedTools: ['Read'], skipPermissions: true },
+    });
+  });
+});
+
+test('saving preferences merge-patches instead of replacing the whole set', async () => {
+  await withDatabase(() => {
+    userPreferencesDb.savePreferences(USER_ID, { theme: 'dark', userLanguage: 'de' });
+    userPreferencesDb.savePreferences(USER_ID, { theme: 'light' });
+
+    assert.deepEqual(userPreferencesDb.getPreferences(USER_ID), {
+      theme: 'light',
+      userLanguage: 'de',
+    });
+  });
+});
+
+test('a preference set to undefined is removed', async () => {
+  await withDatabase(() => {
+    userPreferencesDb.savePreferences(USER_ID, { theme: 'dark', userLanguage: 'de' });
+    userPreferencesDb.savePreferences(USER_ID, { userLanguage: undefined });
+
+    assert.deepEqual(userPreferencesDb.getPreferences(USER_ID), { theme: 'dark' });
+  });
+});
+
+test('one unreadable preference value does not cost the user the others', async () => {
+  await withDatabase(() => {
+    userPreferencesDb.savePreferences(USER_ID, { theme: 'dark' });
+    getConnection()
+      .prepare(
+        `INSERT INTO user_preferences (user_id, preference_key, preference_value)
+         VALUES (?, ?, ?)`
+      )
+      .run(USER_ID, 'broken', 'not json');
+
+    assert.deepEqual(userPreferencesDb.getPreferences(USER_ID), { theme: 'dark' });
+  });
+});
+
+test('drafts round-trip text and queued message per scope', async () => {
+  await withDatabase(() => {
+    sessionDraftsDb.saveDraft(USER_ID, 'session-a', { text: 'half typed', queuedMessage: null });
+    sessionDraftsDb.saveDraft(USER_ID, 'project:p1', {
+      text: '',
+      queuedMessage: { content: 'run it' },
+    });
+
+    const drafts = sessionDraftsDb.getDrafts(USER_ID);
+    const byScope = new Map(drafts.map((draft) => [draft.scope, draft]));
+
+    assert.equal(byScope.get('session-a')?.text, 'half typed');
+    assert.equal(byScope.get('session-a')?.queuedMessage, null);
+    assert.equal(byScope.get('project:p1')?.text, '');
+    assert.deepEqual(byScope.get('project:p1')?.queuedMessage, { content: 'run it' });
+  });
+});
+
+test('saving an empty draft deletes the row rather than keeping a blank one', async () => {
+  await withDatabase(() => {
+    sessionDraftsDb.saveDraft(USER_ID, 'session-a', { text: 'typed', queuedMessage: null });
+    sessionDraftsDb.saveDraft(USER_ID, 'session-a', { text: '', queuedMessage: null });
+
+    assert.deepEqual(sessionDraftsDb.getDrafts(USER_ID), []);
+  });
+});
+
+test('deleteDraft removes only the named scope', async () => {
+  await withDatabase(() => {
+    sessionDraftsDb.saveDraft(USER_ID, 'session-a', { text: 'a', queuedMessage: null });
+    sessionDraftsDb.saveDraft(USER_ID, 'session-b', { text: 'b', queuedMessage: null });
+
+    sessionDraftsDb.deleteDraft(USER_ID, 'session-a');
+
+    assert.deepEqual(
+      sessionDraftsDb.getDrafts(USER_ID).map((draft) => draft.scope),
+      ['session-b'],
+    );
+  });
+});

package/server/modules/file-tree/file-tree.service.ts

@@ -11,9 +11,13 @@ import type {
 } from '@/shared/types.js';
 import { AppError, FORBIDDEN_WORKSPACE_PATHS, normalizeProjectPath } from '@/shared/utils.js';
 
+const HARD_EXCLUDED_DIRECTORY_NAMES = new Set([
+  'node_modules', '.git', '.svn', '.hg',
+]);
+
 const IGNORED_DIRECTORY_NAMES = new Set([
-  'node_modules', 'dist', 'build', '.next', '.nuxt', '.cache', '.parcel-cache',
-  '.git', '.svn', '.hg',
+  ...HARD_EXCLUDED_DIRECTORY_NAMES,
+  'dist', 'build', '.next', '.nuxt', '.cache', '.parcel-cache',
   '__pycache__', '.pytest_cache', '.mypy_cache', '.tox', 'venv', '.venv',
   'target', 'vendor',
   '.gradle', '.idea', 'coverage', '.nyc_output',
@@ -36,6 +40,15 @@ const MAXIMUM_FILE_TREE_ENTRIES = 10_000;
 
 type FileTreeEntryFilter = (entryPath: string, isDirectory: boolean) => boolean;
 
+function includeEntryByHardExclusions(entryPath: string, isDirectory: boolean): boolean {
+  return !isDirectory || !HARD_EXCLUDED_DIRECTORY_NAMES.has(path.basename(entryPath));
+}
+
+function includeEntryByFallbackDirectoryNames(entryPath: string, isDirectory: boolean): boolean {
+  return includeEntryByHardExclusions(entryPath, isDirectory)
+    && (!isDirectory || !IGNORED_DIRECTORY_NAMES.has(path.basename(entryPath)));
+}
+
 function createFileTreeError(message: string, statusCode: number, code: string): AppError {
   return new AppError(message, { statusCode, code });
 }
@@ -146,6 +159,8 @@ function createGitignoreEntryFilter(
   const gitignore = ignore().add(gitignoreContent);
 
   return (entryPath, isDirectory) => {
+    if (!includeEntryByHardExclusions(entryPath, isDirectory)) return false;
+
     const relativePath = path.relative(projectRoot, entryPath).split(path.sep).join('/');
     const matchPath = isDirectory ? `${relativePath}/` : relativePath;
     return !gitignore.ignores(matchPath);
@@ -191,17 +206,13 @@ export function createFileTreeService(dependencies: FileTreeServiceDependencies)
     try {
       for await (const entry of fileSystem.openDirectory(directoryPath)) {
         const isDirectory = entry.isDirectory();
-        if (isDirectory && IGNORED_DIRECTORY_NAMES.has(entry.name)) {
-          continue;
-        }
         if (!includeEntry(path.join(directoryPath, entry.name), isDirectory)) {
           continue;
         }
 
-        // Charged after ignore filtering so generated directories and
-        // .gitignore exclusions never consume the budget. Every recursive
-        // branch shares one counter, so the cap applies to the whole tree
-        // rather than per directory.
+        // Charged after visibility filtering so ignored entries never consume
+        // the budget. Every recursive branch shares one counter, so the cap
+        // applies to the whole tree rather than per directory.
         if (remainingEntries.value <= 0) {
           throw createFileTreeError(
             `Project file tree exceeds the ${MAXIMUM_FILE_TREE_ENTRIES.toLocaleString()} entry limit. Choose a narrower project directory or add ignore rules.`,
@@ -233,7 +244,7 @@ export function createFileTreeService(dependencies: FileTreeServiceDependencies)
     directoryPath: string,
     maximumDepth: number,
     currentDepth = 0,
-    includeEntry: FileTreeEntryFilter = () => true,
+    includeEntry: FileTreeEntryFilter = includeEntryByFallbackDirectoryNames,
     remainingEntries = { value: MAXIMUM_FILE_TREE_ENTRIES },
   ): Promise<FileTreeNode[]> {
     const visibleEntries = await collectVisibleEntries(directoryPath, includeEntry, remainingEntries);

package/server/modules/file-tree/tests/file-tree.service.test.ts

@@ -87,37 +87,67 @@ function createDependencies(
   };
 }
 
-test('listProjectFiles builds a sorted tree and skips generated directories', async () => {
+test('listProjectFiles applies gitignore alongside hard directory exclusions', async () => {
   const projectRoot = path.resolve('file-tree-test-project');
+  const documentationDirectory = path.join(projectRoot, 'docs');
+  const buildDocumentationDirectory = path.join(documentationDirectory, 'build');
+  const gitDirectory = path.join(projectRoot, '.git');
+  const nodeModulesDirectory = path.join(projectRoot, 'node_modules');
   const sourceDirectory = path.join(projectRoot, 'src');
+  const readDirectories: string[] = [];
   const fileSystem = createFakeFileSystem({
     access: async () => undefined,
+    readTextFile: async (filePath) => {
+      assert.equal(filePath, path.join(projectRoot, '.gitignore'));
+      return '*.log';
+    },
     openDirectory: createDirectoryReader((directoryPath) => {
+      readDirectories.push(directoryPath);
       if (directoryPath === projectRoot) {
         return [
+          createDirectoryEntry('.git', true),
           createDirectoryEntry('node_modules', true),
           createDirectoryEntry('README.md', false),
+          createDirectoryEntry('docs', true),
           createDirectoryEntry('src', true),
         ];
       }
+      if (directoryPath === documentationDirectory) {
+        return [createDirectoryEntry('build', true)];
+      }
+      if (directoryPath === buildDocumentationDirectory) {
+        return [createDirectoryEntry('foo.md', false)];
+      }
       if (directoryPath === sourceDirectory) {
         return [createDirectoryEntry('index.ts', false)];
       }
       return [];
     }),
-    lstat: async (candidatePath) => createStats(candidatePath === sourceDirectory, 0o754),
+    lstat: async (candidatePath) => createStats(
+      candidatePath === documentationDirectory
+        || candidatePath === buildDocumentationDirectory
+        || candidatePath === sourceDirectory
+        || candidatePath === gitDirectory
+        || candidatePath === nodeModulesDirectory,
+      0o754,
+    ),
   });
   const service = createFileTreeService(createDependencies(fileSystem, projectRoot));
 
-  const tree = await service.listProjectFiles('project-1');
+  const tree = await service.listProjectFiles('project-1', { respectGitignore: true });
 
-  assert.deepEqual(tree.map((entry) => entry.name), ['src', 'README.md']);
-  const sourceEntry = tree[0];
+  assert.deepEqual(tree.map((entry) => entry.name), ['docs', 'src', 'README.md']);
+  const documentationEntry = tree[0];
+  assert.deepEqual(documentationEntry?.children?.map((entry) => entry.name), ['build']);
+  assert.deepEqual(documentationEntry?.children?.[0]?.children?.map((entry) => entry.name), ['foo.md']);
+  const sourceEntry = tree[1];
   assert.ok(sourceEntry);
   assert.equal(sourceEntry.type, 'directory');
   assert.equal(sourceEntry.permissions, '754');
   assert.equal(sourceEntry.permissionsRwx, 'rwxr-xr--');
   assert.deepEqual(sourceEntry.children?.map((entry) => entry.name), ['index.ts']);
+  assert.equal(readDirectories.includes(gitDirectory), false);
+  assert.equal(readDirectories.includes(nodeModulesDirectory), false);
 });
 
 test('listProjectFiles excludes gitignored entries only when requested', async () => {
@@ -167,23 +197,47 @@ test('listProjectFiles excludes gitignored entries only when requested', async (
   assert.equal(readDirectories.includes(cacheDirectory), false);
 });
 
-test('listProjectFiles returns the normal tree when no gitignore exists', async () => {
+test('listProjectFiles falls back to conventional directory names when no gitignore exists', async () => {
   const projectRoot = path.resolve('file-tree-test-project');
+  const documentationDirectory = path.join(projectRoot, 'docs');
+  const buildDocumentationDirectory = path.join(documentationDirectory, 'build');
+  const nodeModulesDirectory = path.join(projectRoot, 'node_modules');
+  const readDirectories: string[] = [];
   const fileSystem = createFakeFileSystem({
     access: async () => undefined,
     readTextFile: async () => {
       throw Object.assign(new Error('missing'), { code: 'ENOENT' });
     },
-    openDirectory: createDirectoryReader((directoryPath) => directoryPath === projectRoot
-      ? [createDirectoryEntry('debug.log', false)]
-      : []),
-    lstat: async () => createStats(false, 0o644),
+    openDirectory: createDirectoryReader((directoryPath) => {
+      readDirectories.push(directoryPath);
+      if (directoryPath === projectRoot) {
+        return [
+          createDirectoryEntry('debug.log', false),
+          createDirectoryEntry('docs', true),
+          createDirectoryEntry('node_modules', true),
+        ];
+      }
+      if (directoryPath === documentationDirectory) {
+        return [
+          createDirectoryEntry('build', true),
+          createDirectoryEntry('guide.md', false),
+        ];
+      }
+      if (directoryPath === buildDocumentationDirectory) {
+        return [createDirectoryEntry('generated.md', false)];
+      }
+      return [];
+    }),
+    lstat: async (candidatePath) => createStats(candidatePath === documentationDirectory, 0o644),
   });
   const service = createFileTreeService(createDependencies(fileSystem, projectRoot));
 
   const tree = await service.listProjectFiles('project-1', { respectGitignore: true });
 
-  assert.deepEqual(tree.map((entry) => entry.name), ['debug.log']);
+  assert.deepEqual(tree.map((entry) => entry.name), ['docs', 'debug.log']);
+  assert.deepEqual(tree[0]?.children?.map((entry) => entry.name), ['guide.md']);
+  assert.equal(readDirectories.includes(nodeModulesDirectory), false);
+  assert.equal(readDirectories.includes(buildDocumentationDirectory), false);
 });
 
 test('listProjectFiles rejects a tree that exceeds the server entry limit', async () => {

package/server/modules/git/git-branch.service.ts

@@ -0,0 +1,43 @@
+import { AppError } from '@/shared/utils.js';
+
+type GitCommandResult = {
+  stdout: string;
+  stderr: string;
+};
+
+type GitCommandRunner = (
+  command: string,
+  args: string[],
+  options: { cwd: string },
+) => Promise<GitCommandResult>;
+
+type DeleteLocalBranchInput = {
+  projectPath: string;
+  branch: string;
+  force: boolean;
+  runCommand: GitCommandRunner;
+};
+
+/** Used by the Git routes module to safely delete a non-current local branch. */
+export async function deleteLocalBranch(input: DeleteLocalBranchInput): Promise<string> {
+  const { stdout: currentBranch } = await input.runCommand(
+    'git',
+    ['branch', '--show-current'],
+    { cwd: input.projectPath },
+  );
+
+  if (currentBranch.trim() === input.branch) {
+    throw new AppError('Cannot delete the currently checked-out branch', {
+      code: 'GIT_CURRENT_BRANCH_DELETE',
+      statusCode: 400,
+    });
+  }
+
+  const deleteFlag = input.force ? '-D' : '-d';
+  const { stdout } = await input.runCommand(
+    'git',
+    ['branch', deleteFlag, '--', input.branch],
+    { cwd: input.projectPath },
+  );
+  return stdout;
+}

package/server/modules/git/git.routes.ts

@@ -8,6 +8,7 @@ import { AppError } from '@/shared/utils.js';
 
 // cross-spawn: drop-in spawn with Windows .cmd/PATHEXT resolution.
 import { parseGitLogWithStats, parseGitStatusOutput } from './git-parsing.service.js';
+import { deleteLocalBranch } from './git-branch.service.js';
 
 type GitRouterDependencies = {
   fileSystem: typeof import('node:fs/promises');
@@ -839,26 +840,32 @@ router.post('/create-branch', async (req, res) => {
 
 // Delete a local branch
 router.post('/delete-branch', async (req, res) => {
-  const { project, branch } = req.body;
+  const { project, branch, force = false } = req.body;
 
   if (!project || !branch) {
     return res.status(400).json({ error: 'Project id and branch name are required' });
   }
 
+  if (typeof force !== 'boolean') {
+    return res.status(400).json({ error: 'force must be a boolean' });
+  }
+
   try {
     const projectPath = await getActualProjectPath(project);
     await validateGitRepository(projectPath);
-
-    // Safety: cannot delete the currently checked-out branch
-    const { stdout: currentBranch } = await spawnAsync('git', ['branch', '--show-current'], { cwd: projectPath });
-    if (currentBranch.trim() === branch) {
-      return res.status(400).json({ error: 'Cannot delete the currently checked-out branch' });
-    }
-
-    const { stdout } = await spawnAsync('git', ['branch', '-d', branch], { cwd: projectPath });
+    validateBranchName(branch);
+    const stdout = await deleteLocalBranch({
+      projectPath,
+      branch,
+      force,
+      runCommand: spawnAsync,
+    });
     res.json({ success: true, output: stdout });
   } catch (error) {
     console.error('Git delete branch error:', error);
+    if (error instanceof AppError) {
+      return res.status(error.statusCode).json({ error: error.message });
+    }
     res.status(500).json({ error: error.message });
   }
 });

package/server/modules/git/tests/git-branch.service.test.ts

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { deleteLocalBranch } from '../git-branch.service.js';
+
+test('deleteLocalBranch uses safe deletion by default', async () => {
+  const commands: string[][] = [];
+  const output = await deleteLocalBranch({
+    projectPath: '/workspace/repo',
+    branch: 'feature/safe-delete',
+    force: false,
+    runCommand: async (_command, args) => {
+      commands.push(args);
+      return {
+        stdout: args.includes('--show-current') ? 'main\n' : 'Deleted branch feature/safe-delete.\n',
+        stderr: '',
+      };
+    },
+  });
+
+  assert.equal(output, 'Deleted branch feature/safe-delete.\n');
+  assert.deepEqual(commands, [
+    ['branch', '--show-current'],
+    ['branch', '-d', '--', 'feature/safe-delete'],
+  ]);
+});
+
+test('deleteLocalBranch uses force deletion only when requested', async () => {
+  const commands: string[][] = [];
+  await deleteLocalBranch({
+    projectPath: '/workspace/repo',
+    branch: 'feature/unmerged',
+    force: true,
+    runCommand: async (_command, args) => {
+      commands.push(args);
+      return { stdout: args.includes('--show-current') ? 'main\n' : '', stderr: '' };
+    },
+  });
+
+  assert.deepEqual(commands, [
+    ['branch', '--show-current'],
+    ['branch', '-D', '--', 'feature/unmerged'],
+  ]);
+});
+
+test('deleteLocalBranch refuses to delete the current branch even when forced', async () => {
+  await assert.rejects(
+    deleteLocalBranch({
+      projectPath: '/workspace/repo',
+      branch: 'feature/current',
+      force: true,
+      runCommand: async () => ({ stdout: 'feature/current\n', stderr: '' }),
+    }),
+    (error: unknown) => {
+      assert.equal((error as { code?: string }).code, 'GIT_CURRENT_BRANCH_DELETE');
+      assert.equal((error as { statusCode?: number }).statusCode, 400);
+      return true;
+    },
+  );
+});