test: split cli tests from source tree (#216)

* feat(cli): define full warehouse dialect contract

* test(cli): keep dialect edge tests focused

* fix(cli): stabilize dialect contract foundation

* refactor(connectors): own read-only query preparation

* refactor(connectors): resolve dialects through registry

* refactor(connectors): keep concrete dialect classes internal

* chore(workspace): enforce dialect import boundary

* refactor(cli): resolve relationship dialect at scan boundary

* refactor(cli): use dialect display parsing for entity details

* refactor(cli): use dialect display parsing for warehouse catalog

* refactor(cli): use dialect SQL in relationship workflows

* test(cli): verify solid dialect scan workflow closure

* test: split cli tests from source tree

* refactor(cli): standardize BigQuery scope listing

* feat(sqlite): implement connector scope listing

* test(connectors): cover required table listing

* feat(cli): add warehouse driver registry

* refactor(setup): route scope discovery through driver registry

* refactor(cli): route local query execution through driver registry

* refactor(historic-sql): route dialect support through driver registry

* refactor(cli): test warehouse connections through driver registry

* fix(cli): close driver registry type export gaps

* Improve setup daemon diagnostics

* refactor(setup): centralize rail-prefixed diagnostics + query-history fallback

Extract errorMessage, writePrefixedLines, and flushPrefixedBufferedCommandOutput
into clack.ts so the setup wizard, managed daemons, and embedding/agent steps
share one rail-formatted writer. setup-databases.ts also adds a
"disable query history and retry" option when the schema-context build fails
and query history is the likely culprit, surfaced via a new
failed-query-history-unavailable status.

* fix(cli): carry catalog through the picker so BigQuery/Snowflake/SQL Server scope filters match

The setup picker's KtxTableListEntry was a 2-level { schema, name }, so
qualifiedTableId always wrote db.name into enabled_tables. When BigQuery,
Snowflake, or SQL Server later ran fast ingest, their introspect step filtered
the scope set with scopedTableNames(scope, { catalog: projectId|database, db })
— catalog was non-null on the introspect side but null in the scope refs, so
every entry was rejected, the live-database adapter staged zero table files,
and detect() failed with 'Adapter "live-database" did not recognize fetched
source output'.

Align the picker boundary with the canonical 3-level KtxTableRef:

- Add catalog: string | null to KtxTableListEntry.
- BigQuery/Snowflake/SQL Server listTables populate catalog from the
  resolved projectId / database; Postgres/MySQL/ClickHouse/SQLite set null.
- qualifiedTableId emits catalog.schema.name when catalog is non-null
  (resolveEnabledTables already accepts the 3-part shape) and
  schemasFromEnabledTables now goes through parseDottedTableEntry so it
  recovers the schema correctly from both 2-part and 3-part entries.
- Export parseDottedTableEntry from enabled-tables.ts (@internal) for picker
  reuse.

Update listTables expectations in all seven connector tests and the setup /
picker test fixtures. Add a picker regression test that covers the
catalog-bearing round-trip (save + refine).

* fix(cli): allow debug telemetry under opt-out env

packages/cli/test/context/core/config-reference.test.ts

@@ -0,0 +1,34 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { resolveKtxConfigReference, resolveKtxHomePath } from '../../../src/context/core/config-reference.js';
+
+describe('KTX config references', () => {
+  it('resolves env references without returning empty values', () => {
+    expect(resolveKtxConfigReference('env:AI_GATEWAY_API_KEY', { AI_GATEWAY_API_KEY: ' gateway-key ' })).toBe(
+      'gateway-key',
+    );
+    expect(resolveKtxConfigReference('env:AI_GATEWAY_API_KEY', { AI_GATEWAY_API_KEY: '   ' })).toBeUndefined();
+    expect(resolveKtxConfigReference('env:AI_GATEWAY_API_KEY', {})).toBeUndefined();
+  });
+
+  it('resolves file references and trims file content', async () => {
+    const dir = join(tmpdir(), `ktx-config-reference-${process.pid}`);
+    await mkdir(dir, { recursive: true });
+    const keyPath = join(dir, 'gateway-key.txt');
+    await writeFile(keyPath, 'file-gateway-key\n', 'utf8');
+
+    expect(resolveKtxConfigReference(`file:${keyPath}`, {})).toBe('file-gateway-key');
+  });
+
+  it('returns literal values unchanged after trimming blank-only values', () => {
+    expect(resolveKtxConfigReference('provider/model', {})).toBe('provider/model');
+    expect(resolveKtxConfigReference('  ', {})).toBeUndefined();
+    expect(resolveKtxConfigReference(undefined, {})).toBeUndefined();
+  });
+
+  it('resolves home-prefixed paths', () => {
+    expect(resolveKtxHomePath('~/ktx/key.txt')).toContain('/ktx/key.txt');
+  });
+});

packages/cli/test/context/core/git.service.assert-worktree-clean.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { SimpleGit } from 'simple-git';
+import type { KtxCoreConfig } from '../../../src/context/core/config.js';
+import { createSimpleGit } from '../../../src/context/core/git-env.js';
+import { GitService } from '../../../src/context/core/git.service.js';
+
+describe('GitService.assertWorktreeClean', () => {
+  let workdir: string;
+  let git: SimpleGit;
+  let gitService: GitService;
+
+  beforeEach(async () => {
+    workdir = await mkdtemp(join(tmpdir(), 'gitsvc-clean-'));
+    git = createSimpleGit(workdir);
+    await git.init();
+    await git.addConfig('user.email', 't@test');
+    await git.addConfig('user.name', 'Test');
+    await writeFile(join(workdir, 'init'), 'init');
+    await git.add('.');
+    await git.commit('init');
+    const coreConfig: KtxCoreConfig = {
+      storage: { configDir: workdir, homeDir: workdir },
+      git: { userName: 'Test', userEmail: 't@test' },
+    };
+    gitService = new GitService(coreConfig);
+    (gitService as any).git = git;
+    (gitService as any).configDir = workdir;
+  });
+
+  afterEach(async () => rm(workdir, { recursive: true, force: true }));
+
+  it('does not throw on a clean worktree', async () => {
+    await expect(gitService.assertWorktreeClean()).resolves.toBeUndefined();
+  });
+
+  it('throws when MERGE_HEAD exists', async () => {
+    await writeFile(join(workdir, '.git', 'MERGE_HEAD'), 'deadbeef\n');
+    await expect(gitService.assertWorktreeClean()).rejects.toThrow(/MERGE_HEAD/);
+  });
+
+  it('throws when CHERRY_PICK_HEAD exists', async () => {
+    await writeFile(join(workdir, '.git', 'CHERRY_PICK_HEAD'), 'deadbeef\n');
+    await expect(gitService.assertWorktreeClean()).rejects.toThrow(/CHERRY_PICK_HEAD/);
+  });
+
+  it('throws when REVERT_HEAD exists', async () => {
+    await writeFile(join(workdir, '.git', 'REVERT_HEAD'), 'deadbeef\n');
+    await expect(gitService.assertWorktreeClean()).rejects.toThrow(/REVERT_HEAD/);
+  });
+
+  it('throws when sequencer/todo exists (interrupted multi-commit revert/cherry-pick)', async () => {
+    await mkdir(join(workdir, '.git', 'sequencer'), { recursive: true });
+    await writeFile(join(workdir, '.git', 'sequencer', 'todo'), 'pick deadbeef foo\n');
+    await expect(gitService.assertWorktreeClean()).rejects.toThrow(/sequencer/);
+  });
+
+  it('throws when the index has unmerged paths', async () => {
+    await git.checkoutLocalBranch('a');
+    await writeFile(join(workdir, 'shared'), 'A version');
+    await git.add('.');
+    await git.commit('a');
+    await git.checkout('master').catch(() => git.checkout('main'));
+    await git.checkoutLocalBranch('b');
+    await writeFile(join(workdir, 'shared'), 'B version');
+    await git.add('.');
+    await git.commit('b');
+
+    await git.raw(['merge', 'a']).catch(() => undefined);
+
+    await expect(gitService.assertWorktreeClean()).rejects.toThrow();
+  });
+});

packages/cli/test/context/core/git.service.delete-directories.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdir, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { SimpleGit } from 'simple-git';
+import type { KtxCoreConfig } from '../../../src/context/core/config.js';
+import { createSimpleGit } from '../../../src/context/core/git-env.js';
+import { GitService } from '../../../src/context/core/git.service.js';
+
+describe('GitService.deleteDirectories', () => {
+  let workdir: string;
+  let git: SimpleGit;
+  let gitService: GitService;
+
+  beforeEach(async () => {
+    workdir = await mkdtemp(join(tmpdir(), 'gitsvc-dd-'));
+    git = createSimpleGit(workdir);
+    await git.init();
+    await git.addConfig('user.email', 't@test');
+    await git.addConfig('user.name', 'Test');
+    await writeFile(join(workdir, 'keep'), 'k');
+    await git.add('.');
+    await git.commit('init');
+
+    const coreConfig: KtxCoreConfig = {
+      storage: { configDir: workdir, homeDir: workdir },
+      git: { userName: 'Test', userEmail: 't@test' },
+    };
+    gitService = new GitService(coreConfig);
+    (gitService as any).git = git;
+    (gitService as any).configDir = workdir;
+  });
+
+  afterEach(async () => rm(workdir, { recursive: true, force: true }));
+
+  it('removes multiple directories in a single commit', async () => {
+    for (const name of ['a', 'b', 'c']) {
+      await mkdir(join(workdir, name), { recursive: true });
+      await writeFile(join(workdir, name, 'f.txt'), name);
+    }
+    await git.add('.');
+    await git.commit('seed 3 dirs');
+    const beforeCommits = (await git.log()).total;
+
+    const result = await gitService.deleteDirectories(['a', 'b'], 'gc: drop a+b', 'System User', 'system@example.com');
+    expect(result.commitHash).toBeTruthy();
+
+    const entries = await readdir(workdir);
+    expect(entries).not.toContain('a');
+    expect(entries).not.toContain('b');
+    expect(entries).toContain('c');
+
+    const afterCommits = (await git.log()).total;
+    expect(afterCommits).toBe(beforeCommits + 1);
+  });
+
+  it('no-ops and returns a null hash when the input list is empty', async () => {
+    const result = await gitService.deleteDirectories([], 'empty', 'X', 'x@example.com');
+    expect(result.commitHash).toBe('');
+    expect(result.created).toBe(false);
+  });
+
+  it('ignores paths that have already been deleted — commits only the remaining ones', async () => {
+    await mkdir(join(workdir, 'stale'), { recursive: true });
+    await writeFile(join(workdir, 'stale', 'x'), 'x');
+    await git.add('.');
+    await git.commit('seed stale');
+    const result = await gitService.deleteDirectories(
+      ['stale', 'missing'],
+      'gc: drop stale + missing',
+      'System User',
+      'system@example.com',
+    );
+    expect(result.commitHash).toBeTruthy();
+    const entries = await readdir(workdir);
+    expect(entries).not.toContain('stale');
+  });
+});

packages/cli/test/context/core/git.service.patch.test.ts

@@ -0,0 +1,45 @@
+import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { GitService } from '../../../src/context/core/git.service.js';
+
+async function makeGit() {
+  const homeDir = await mkdtemp(join(tmpdir(), 'ktx-git-patch-'));
+  const configDir = join(homeDir, 'config');
+  const git = new GitService({
+    storage: { configDir, homeDir },
+    git: {
+      userName: 'System User',
+      userEmail: 'system@example.com',
+      bootstrapMessage: 'init',
+      bootstrapAuthor: 'system',
+      bootstrapAuthorEmail: 'system@example.com',
+    },
+  });
+  await git.onModuleInit();
+  return { homeDir, configDir, git };
+}
+
+describe('GitService patch helpers', () => {
+  it('collects binary-safe no-rename patches and applies them with --3way --index', async () => {
+    const { homeDir, configDir, git } = await makeGit();
+    await mkdir(join(configDir, 'wiki/global'), { recursive: true });
+    await writeFile(join(configDir, 'wiki/global/page.md'), 'old\n');
+    await git.commitFiles(['wiki/global/page.md'], 'add page', 'System User', 'system@example.com');
+    const base = await git.revParseHead();
+
+    await writeFile(join(configDir, 'wiki/global/page.md'), 'new\n');
+    await git.commitFiles(['wiki/global/page.md'], 'edit page', 'System User', 'system@example.com');
+    const patchPath = join(homeDir, 'proposal.patch');
+    await git.writeBinaryNoRenamePatch(base, 'HEAD', patchPath);
+
+    const targetDir = join(homeDir, 'target');
+    await git.addWorktree(targetDir, 'target', base);
+    const targetGit = git.forWorktree(targetDir);
+    await targetGit.applyPatchFile3WayIndex(patchPath);
+    await targetGit.commitStaged('apply proposal', 'System User', 'system@example.com');
+
+    await expect(readFile(join(targetDir, 'wiki/global/page.md'), 'utf-8')).resolves.toBe('new\n');
+  });
+});

packages/cli/test/context/core/git.service.reset-hard.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { SimpleGit } from 'simple-git';
+import type { KtxCoreConfig } from '../../../src/context/core/config.js';
+import { createSimpleGit } from '../../../src/context/core/git-env.js';
+import { GitService } from '../../../src/context/core/git.service.js';
+
+describe('GitService.resetHardTo', () => {
+  let workdir: string;
+  let git: SimpleGit;
+  let gitService: GitService;
+
+  beforeEach(async () => {
+    workdir = await mkdtemp(join(tmpdir(), 'gitsvc-reset-'));
+    git = createSimpleGit(workdir);
+    await git.init();
+    await git.addConfig('user.email', 't@test');
+    await git.addConfig('user.name', 'Test');
+    await writeFile(join(workdir, 'init'), 'init');
+    await git.add('.');
+    await git.commit('init');
+    const coreConfig: KtxCoreConfig = {
+      storage: { configDir: workdir, homeDir: workdir },
+      git: { userName: 'Test', userEmail: 't@test' },
+    };
+    gitService = new GitService(coreConfig);
+    (gitService as any).git = git;
+    (gitService as any).configDir = workdir;
+  });
+
+  afterEach(async () => rm(workdir, { recursive: true, force: true }));
+
+  it('rewinds HEAD to the target SHA, removing later commits and their files', async () => {
+    const baseSha = (await git.revparse(['HEAD'])).trim();
+    await writeFile(join(workdir, 'a'), 'a1');
+    await git.add('.');
+    await git.commit('a');
+    await writeFile(join(workdir, 'b'), 'b1');
+    await git.add('.');
+    await git.commit('b');
+
+    await gitService.resetHardTo(baseSha);
+
+    expect((await git.revparse(['HEAD'])).trim()).toBe(baseSha);
+    expect(await readFile(join(workdir, 'a'), 'utf-8').catch(() => null)).toBeNull();
+    expect(await readFile(join(workdir, 'b'), 'utf-8').catch(() => null)).toBeNull();
+  });
+
+  it('is a no-op when target SHA equals current HEAD', async () => {
+    const sha = (await git.revparse(['HEAD'])).trim();
+    await gitService.resetHardTo(sha);
+    expect((await git.revparse(['HEAD'])).trim()).toBe(sha);
+  });
+});

packages/cli/test/context/core/git.service.test.ts

@@ -0,0 +1,450 @@
+import { mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { KtxCoreConfig } from '../../../src/context/core/config.js';
+import { GitService } from '../../../src/context/core/git.service.js';
+
+// These tests drive a real git repo inside a temp directory — simple-git shells out to the
+// system `git` binary. They are fast enough to run as unit tests and catch real issues that
+// would be invisible with mocked git.
+describe('GitService', () => {
+  let service: GitService;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'git-service-spec-'));
+
+    const coreConfig: KtxCoreConfig = {
+      storage: { configDir: tempDir, homeDir: tempDir },
+      git: {
+        userName: 'Test User',
+        userEmail: 'test@example.com',
+        bootstrapMessage: 'Initialize test config repo',
+        bootstrapAuthor: 'test-system',
+        bootstrapAuthorEmail: 'system@example.com',
+      },
+    };
+
+    service = new GitService(coreConfig);
+    await service.onModuleInit();
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  const writeAndCommit = async (filePath: string, content: string, message = 'msg') => {
+    await writeFile(join(tempDir, filePath), content, 'utf-8');
+    return service.commitFile(filePath, message, 'Test', 'test@example.com');
+  };
+
+  describe('cold-start bootstrap commit', () => {
+    it('writes an empty commit on init so HEAD always resolves', async () => {
+      // beforeEach already ran onModuleInit() against an empty temp dir.
+      const head = await service.revParseHead();
+      expect(head).toMatch(/^[0-9a-f]{40}$/);
+    });
+
+    it('does not double-commit when re-initialized', async () => {
+      const before = await service.revParseHead();
+      await service.onModuleInit();
+      const after = await service.revParseHead();
+      expect(after).toBe(before);
+    });
+
+    it('keeps git auto-maintenance attached for deterministic cleanup', async () => {
+      const config = await readFile(join(tempDir, '.git', 'config'), 'utf-8');
+
+      expect(config).toMatch(/\[gc]\n\s+autoDetach = false/);
+      expect(config).toMatch(/\[maintenance]\n\s+autoDetach = false/);
+    });
+
+    it('initializes when release automation sets GIT_ASKPASS', async () => {
+      const releaseEnvDir = await mkdtemp(join(tmpdir(), 'git-service-release-env-'));
+      const previousAskPass = process.env.GIT_ASKPASS;
+      process.env.GIT_ASKPASS = 'echo';
+
+      try {
+        const releaseEnvService = new GitService({
+          storage: { configDir: releaseEnvDir, homeDir: releaseEnvDir },
+          git: {
+            userName: 'Test User',
+            userEmail: 'test@example.com',
+            bootstrapMessage: 'Initialize test config repo',
+            bootstrapAuthor: 'test-system',
+            bootstrapAuthorEmail: 'system@example.com',
+          },
+        });
+
+        await expect(releaseEnvService.onModuleInit()).resolves.toBeUndefined();
+      } finally {
+        if (previousAskPass === undefined) {
+          delete process.env.GIT_ASKPASS;
+        } else {
+          process.env.GIT_ASKPASS = previousAskPass;
+        }
+        await rm(releaseEnvDir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe('commitFile `created` flag', () => {
+    it('is true for a real commit', async () => {
+      const info = await writeAndCommit('a.md', '# Hello');
+      expect(info.created).toBe(true);
+    });
+
+    it('is false on a no-op write (content unchanged)', async () => {
+      await writeAndCommit('a.md', '# Hello');
+      const second = await writeAndCommit('a.md', '# Hello', 'unused');
+      expect(second.created).toBe(false);
+    });
+  });
+
+  describe('addNote / getNote', () => {
+    it('attaches a note and reads it back', async () => {
+      const info = await writeAndCommit('a.md', '# Hello');
+      await service.addNote(info.commitHash, 'Rich message from LLM');
+      expect(await service.getNote(info.commitHash)).toBe('Rich message from LLM');
+    });
+
+    it('returns undefined when no note exists', async () => {
+      const info = await writeAndCommit('a.md', '# Hello');
+      expect(await service.getNote(info.commitHash)).toBeUndefined();
+    });
+
+    it('overwrites an existing note (idempotent retries)', async () => {
+      const info = await writeAndCommit('a.md', '# Hello');
+      await service.addNote(info.commitHash, 'First');
+      await service.addNote(info.commitHash, 'Second');
+      expect(await service.getNote(info.commitHash)).toBe('Second');
+    });
+
+    it('skips empty/whitespace messages silently', async () => {
+      const info = await writeAndCommit('a.md', '# Hello');
+      await service.addNote(info.commitHash, '   ');
+      expect(await service.getNote(info.commitHash)).toBeUndefined();
+    });
+  });
+
+  describe('getFileHistory', () => {
+    it('surfaces enhancedMessage when a note is present', async () => {
+      const info = await writeAndCommit('a.md', '# Hello');
+      await service.addNote(info.commitHash, 'Note body');
+
+      const history = await service.getFileHistory('a.md');
+      expect(history[0]?.enhancedMessage).toBe('Note body');
+    });
+
+    it('leaves enhancedMessage undefined when no note is attached', async () => {
+      await writeAndCommit('a.md', '# Hello');
+      const history = await service.getFileHistory('a.md');
+      expect(history[0]?.enhancedMessage).toBeUndefined();
+    });
+  });
+
+  describe('getCommitDiff', () => {
+    it('returns the patch scoped to the requested path', async () => {
+      const info = await writeAndCommit('a.md', '# Hello');
+      const diff = await service.getCommitDiff(info.commitHash, 'a.md');
+      expect(diff).toContain('diff --git');
+      expect(diff).toContain('Hello');
+    });
+
+    it('handles the repository initial commit without throwing', async () => {
+      const info = await writeAndCommit('first.md', 'first');
+      await expect(service.getCommitDiff(info.commitHash, 'first.md')).resolves.toBeDefined();
+    });
+  });
+
+  describe('squashTo', () => {
+    const writeAsSystem = async (filePath: string, content: string, message = 'msg') => {
+      await writeFile(join(tempDir, filePath), content, 'utf-8');
+      return service.commitFile(filePath, message, 'System User', 'system@example.com');
+    };
+
+    it('collapses 3 commits after preHead into a single commit', async () => {
+      const pre = await writeAsSystem('a.md', 'v1');
+      const preHead = pre.commitHash;
+
+      await writeAsSystem('b.md', 'b', 'add b');
+      await writeAsSystem('c.md', 'c', 'add c');
+      await writeAsSystem('a.md', 'v2', 'update a');
+
+      const result = await service.squashTo(preHead, {
+        message: 'Ingest: bundle 3 writes',
+        author: 'System User',
+        authorEmail: 'system@example.com',
+      });
+
+      expect(result.squashed).toBe(true);
+      expect(result.squashedCount).toBe(3);
+      expect(result.commitHash).toBeTruthy();
+      expect(result.commitHash).not.toBe(preHead);
+      const commitHash = result.commitHash;
+      if (!commitHash) {
+        throw new Error('Expected squash commit hash');
+      }
+
+      // The squashed commit should preserve the final tree state.
+      const fileAtSquash = await service.getFileAtCommit('a.md', commitHash);
+      expect(fileAtSquash).toBe('v2');
+      const bAtSquash = await service.getFileAtCommit('b.md', commitHash);
+      expect(bAtSquash).toBe('b');
+    });
+
+    it('is a no-op when preHead equals HEAD', async () => {
+      const pre = await writeAsSystem('a.md', 'v1');
+
+      const result = await service.squashTo(pre.commitHash, {
+        message: 'nothing to squash',
+        author: 'System User',
+        authorEmail: 'system@example.com',
+      });
+
+      expect(result.squashed).toBe(false);
+      expect(result.commitHash).toBe(pre.commitHash);
+    });
+
+    it('skips squash when a foreign-author commit sits between preHead and HEAD', async () => {
+      const pre = await writeAsSystem('a.md', 'v1');
+      const preHead = pre.commitHash;
+
+      await writeAsSystem('b.md', 'from us', 'ours');
+      // Foreign commit
+      await writeAndCommit('c.md', 'from someone else', 'foreign');
+      await writeAsSystem('d.md', 'ours again', 'ours 2');
+
+      const result = await service.squashTo(preHead, {
+        message: 'should be skipped',
+        author: 'System User',
+        authorEmail: 'system@example.com',
+      });
+
+      expect(result.squashed).toBe(false);
+      expect(result.reason).toContain('foreign');
+      expect(result.squashedCount).toBe(3);
+    });
+
+    it('returns cleanly when preHead is empty (no starting commit)', async () => {
+      const result = await service.squashTo('', {
+        message: 'would have squashed',
+        author: 'System User',
+        authorEmail: 'system@example.com',
+      });
+
+      expect(result.squashed).toBe(false);
+      expect(result.commitHash).toBeNull();
+    });
+  });
+
+  describe('worktree lifecycle', () => {
+    // macOS canonicalizes tmp paths (/var/folders → /private/var/folders) when git
+    // returns them from `worktree list`. Resolve through realpath() before comparing.
+    const canonicalSiblingPath = async (suffix: string): Promise<string> => {
+      const parent = await realpath(join(tempDir, '..'));
+      return join(parent, `wt-${Date.now()}-${suffix}`);
+    };
+
+    it('addWorktree creates a branch + directory at the given startSha', async () => {
+      const { commitHash } = await writeAndCommit('seed.md', 'seed');
+      const wtDir = await canonicalSiblingPath('add');
+      await service.addWorktree(wtDir, 'session/alpha', commitHash);
+      const list = await service.listWorktrees();
+      expect(list.find((e) => e.path === wtDir && e.branch === 'refs/heads/session/alpha')).toBeTruthy();
+      await service.removeWorktree(wtDir).catch(() => undefined);
+      await rm(wtDir, { recursive: true, force: true }).catch(() => undefined);
+    });
+
+    it('removeWorktree detaches the worktree entry', async () => {
+      const { commitHash } = await writeAndCommit('seed.md', 'seed');
+      const wtDir = await canonicalSiblingPath('rm');
+      await service.addWorktree(wtDir, 'session/beta', commitHash);
+      await service.removeWorktree(wtDir);
+      const list = await service.listWorktrees();
+      expect(list.find((e) => e.path === wtDir)).toBeFalsy();
+    });
+
+    it('deleteBranch removes a branch ref', async () => {
+      const { commitHash } = await writeAndCommit('seed.md', 'seed');
+      const wtDir = await canonicalSiblingPath('br');
+      await service.addWorktree(wtDir, 'session/gamma', commitHash);
+      await service.removeWorktree(wtDir);
+      await service.deleteBranch('session/gamma', true);
+      const branches = await (service as unknown as { git: import('simple-git').SimpleGit }).git.branchLocal();
+      expect(branches.all).not.toContain('session/gamma');
+      await rm(wtDir, { recursive: true, force: true }).catch(() => undefined);
+    });
+  });
+
+  describe('forWorktree', () => {
+    it('returns a GitService whose operations run inside the given worktree', async () => {
+      const { commitHash } = await writeAndCommit('seed.md', 'seed');
+      const parent = await realpath(join(tempDir, '..'));
+      const wtDir = join(parent, `wt-${Date.now()}-fw`);
+      await service.addWorktree(wtDir, 'session/delta', commitHash);
+
+      const scoped = service.forWorktree(wtDir);
+      expect(await scoped.revParseHead()).toBe(commitHash);
+
+      await service.removeWorktree(wtDir).catch(() => undefined);
+      await rm(wtDir, { recursive: true, force: true }).catch(() => undefined);
+    });
+
+    it('serializes concurrent commits from scoped services targeting the same worktree', async () => {
+      const { commitHash } = await writeAndCommit('seed.md', 'seed');
+      const parent = await realpath(join(tempDir, '..'));
+      const wtDir = join(parent, `wt-${Date.now()}-fw-concurrent`);
+      await service.addWorktree(wtDir, 'session/concurrent', commitHash);
+
+      const first = service.forWorktree(wtDir);
+      const second = service.forWorktree(wtDir);
+      await writeFile(join(wtDir, 'a.md'), 'a\n', 'utf-8');
+      await writeFile(join(wtDir, 'b.md'), 'b\n', 'utf-8');
+
+      const [a, b] = await Promise.all([
+        first.commitFile('a.md', 'add a', 'System User', 'system@example.com'),
+        second.commitFile('b.md', 'add b', 'System User', 'system@example.com'),
+      ]);
+
+      expect(a.commitHash).toMatch(/^[0-9a-f]{40}$/);
+      expect(b.commitHash).toMatch(/^[0-9a-f]{40}$/);
+      await expect(first.getFileAtCommit('a.md', a.commitHash)).resolves.toBe('a\n');
+      await expect(second.getFileAtCommit('b.md', b.commitHash)).resolves.toBe('b\n');
+
+      await service.removeWorktree(wtDir).catch(() => undefined);
+      await rm(wtDir, { recursive: true, force: true }).catch(() => undefined);
+    });
+  });
+
+  describe('squashMergeIntoMain', () => {
+    it('merges a session branch as one commit on main, returning the new SHA + touched paths', async () => {
+      const { commitHash: baseSha } = await writeAndCommit('seed.md', 'seed');
+      const parent = await realpath(join(tempDir, '..'));
+      const wtDir = join(parent, `wt-${Date.now()}-sm`);
+      await service.addWorktree(wtDir, 'session/happy', baseSha);
+
+      const scoped = service.forWorktree(wtDir);
+      await writeFile(join(wtDir, 'a.yaml'), 'one: 1\n', 'utf-8');
+      await scoped.commitFile('a.yaml', 'wip a', 'System User', 'system@example.com');
+      await writeFile(join(wtDir, 'b.yaml'), 'two: 2\n', 'utf-8');
+      await scoped.commitFile('b.yaml', 'wip b', 'System User', 'system@example.com');
+
+      const result = await service.squashMergeIntoMain(
+        'session/happy',
+        'System User',
+        'system@example.com',
+        'Memory capture: 2 files [chat=abcd1234]',
+      );
+
+      expect(result.ok).toBe(true);
+      if (!result.ok) {
+        throw new Error('unreachable');
+      }
+      expect(result.squashSha).toMatch(/^[0-9a-f]{40}$/);
+      expect(result.touchedPaths.sort()).toEqual(['a.yaml', 'b.yaml']);
+
+      const mainHead = await service.revParseHead();
+      expect(mainHead).toBe(result.squashSha);
+      expect(mainHead).not.toBe(baseSha);
+
+      await service.removeWorktree(wtDir).catch(() => undefined);
+      await rm(wtDir, { recursive: true, force: true }).catch(() => undefined);
+    });
+
+    it('returns ok with empty touchedPaths when the session branch has no diff vs main', async () => {
+      const { commitHash: baseSha } = await writeAndCommit('seed.md', 'seed');
+      const parent = await realpath(join(tempDir, '..'));
+      const wtDir = join(parent, `wt-${Date.now()}-sm-empty`);
+      await service.addWorktree(wtDir, 'session/empty', baseSha);
+
+      const result = await service.squashMergeIntoMain(
+        'session/empty',
+        'System User',
+        'system@example.com',
+        'should be a no-op',
+      );
+
+      expect(result.ok).toBe(true);
+      if (!result.ok) {
+        throw new Error('unreachable');
+      }
+      expect(result.touchedPaths).toEqual([]);
+      expect(result.squashSha).toBe(baseSha);
+
+      await service.removeWorktree(wtDir).catch(() => undefined);
+      await rm(wtDir, { recursive: true, force: true }).catch(() => undefined);
+    });
+
+    it('returns conflict=true and leaves main clean when session+main touched same file differently', async () => {
+      await writeAndCommit('shared.yaml', 'base\n');
+      const base = await service.revParseHead();
+      if (!base) {
+        throw new Error('no base head');
+      }
+
+      const parent = await realpath(join(tempDir, '..'));
+      const wtDir = join(parent, `wt-${Date.now()}-conf`);
+      await service.addWorktree(wtDir, 'session/conf', base);
+      const scoped = service.forWorktree(wtDir);
+      await writeFile(join(wtDir, 'shared.yaml'), 'session-edit\n', 'utf-8');
+      await scoped.commitFile('shared.yaml', 'session edit', 'System User', 'system@example.com');
+
+      // Main edits the same file a different way, after the session branched.
+      await writeAndCommit('shared.yaml', 'main-edit\n');
+
+      const result = await service.squashMergeIntoMain(
+        'session/conf',
+        'System User',
+        'system@example.com',
+        'Memory capture: 1 file [chat=dead1234]',
+      );
+
+      expect(result.ok).toBe(false);
+      if (result.ok) {
+        throw new Error('unreachable');
+      }
+      expect(result.conflict).toBe(true);
+      expect(result.conflictPaths).toContain('shared.yaml');
+
+      const status = await (service as unknown as { git: import('simple-git').SimpleGit }).git.status();
+      expect(status.isClean()).toBe(true);
+
+      await service.removeWorktree(wtDir).catch(() => undefined);
+      await rm(wtDir, { recursive: true, force: true }).catch(() => undefined);
+    });
+
+    it('reports untracked files that would be overwritten by the squash merge', async () => {
+      const { commitHash: baseSha } = await writeAndCommit('seed.md', 'seed');
+      const parent = await realpath(join(tempDir, '..'));
+      const wtDir = join(parent, `wt-${Date.now()}-untracked`);
+      await service.addWorktree(wtDir, 'session/untracked', baseSha);
+
+      const scoped = service.forWorktree(wtDir);
+      await writeFile(join(wtDir, 'knowledge.md'), 'session version\n', 'utf-8');
+      await scoped.commitFile('knowledge.md', 'session write', 'System User', 'system@example.com');
+      await writeFile(join(tempDir, 'knowledge.md'), 'untracked local version\n', 'utf-8');
+
+      const result = await service.squashMergeIntoMain(
+        'session/untracked',
+        'System User',
+        'system@example.com',
+        'Memory capture: 1 file [chat=untracked]',
+      );
+
+      expect(result.ok).toBe(false);
+      if (result.ok) {
+        throw new Error('unreachable');
+      }
+      expect(result.conflict).toBe(true);
+      expect(result.conflictPaths).toEqual(['knowledge.md']);
+
+      const status = await (service as unknown as { git: import('simple-git').SimpleGit }).git.status();
+      expect(status.not_added).toContain('knowledge.md');
+
+      await service.removeWorktree(wtDir).catch(() => undefined);
+      await rm(wtDir, { recursive: true, force: true }).catch(() => undefined);
+    });
+  });
+});

packages/cli/test/context/core/session-worktree.service.test.ts

@@ -0,0 +1,124 @@
+import { mkdtemp, realpath, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { KtxCoreConfig } from '../../../src/context/core/config.js';
+import { GitService } from '../../../src/context/core/git.service.js';
+import { SessionWorktreeService, type WorktreeConfigPort } from '../../../src/context/core/session-worktree.service.js';
+
+interface TestWorktreeConfig extends WorktreeConfigPort<TestWorktreeConfig> {
+  workdir?: string;
+}
+
+// SessionWorktreeService glues a real GitService to a scoped config adapter.
+describe('SessionWorktreeService', () => {
+  let sessionService: SessionWorktreeService<TestWorktreeConfig>;
+  let gitService: GitService;
+  let homeDir: string;
+
+  beforeEach(async () => {
+    homeDir = await mkdtemp(join(tmpdir(), 'sws-spec-'));
+    homeDir = await realpath(homeDir);
+
+    const coreConfig: KtxCoreConfig = {
+      storage: { configDir: homeDir, homeDir },
+      git: {
+        userName: 'System User',
+        userEmail: 'system@example.com',
+        bootstrapMessage: 'Initialize test config repo',
+        bootstrapAuthor: 'test-system',
+        bootstrapAuthorEmail: 'system@example.com',
+      },
+    };
+
+    gitService = new GitService(coreConfig);
+    await gitService.onModuleInit();
+    const configService: TestWorktreeConfig = {
+      forWorktree: vi.fn(
+        (workdir: string): TestWorktreeConfig => ({ workdir, forWorktree: configService.forWorktree }),
+      ),
+    };
+    sessionService = new SessionWorktreeService({
+      coreConfig,
+      gitService,
+      configService,
+    });
+  });
+
+  afterEach(async () => {
+    await rm(homeDir, { recursive: true, force: true });
+  });
+
+  describe('create', () => {
+    it('creates a worktree + branch and returns scoped services', async () => {
+      const baseSha = await gitService.revParseHead();
+      if (!baseSha) {
+        throw new Error('no base sha');
+      }
+
+      const session = await sessionService.create('chat-abc', baseSha);
+
+      expect(session.workdir).toBe(join(homeDir, '.worktrees', 'session-chat-abc'));
+      expect(session.branch).toBe('session/chat-abc');
+      expect(session.baseSha).toBe(baseSha);
+      const stats = await stat(session.workdir);
+      expect(stats.isDirectory()).toBe(true);
+
+      // Scoped git instance reports the worktree's HEAD (= baseSha at creation time).
+      expect(await session.git.revParseHead()).toBe(baseSha);
+
+      const list = await gitService.listWorktrees();
+      expect(list.find((e) => e.path === session.workdir)).toBeTruthy();
+    });
+
+    it('appends a timestamp suffix when the primary dir already exists', async () => {
+      const baseSha = await gitService.revParseHead();
+      if (!baseSha) {
+        throw new Error('no base sha');
+      }
+
+      const first = await sessionService.create('chat-dup', baseSha);
+      const second = await sessionService.create('chat-dup', baseSha);
+
+      expect(first.workdir).not.toBe(second.workdir);
+      expect(second.branch).toMatch(/^session\/chat-dup-\d+$/);
+    });
+  });
+
+  describe('cleanup', () => {
+    it('success removes the worktree dir and deletes the branch', async () => {
+      const baseSha = await gitService.revParseHead();
+      if (!baseSha) {
+        throw new Error('no base sha');
+      }
+
+      const session = await sessionService.create('chat-cleanup-ok', baseSha);
+      await sessionService.cleanup(session, 'success');
+
+      const list = await gitService.listWorktrees();
+      expect(list.find((e) => e.path === session.workdir)).toBeFalsy();
+      await expect(stat(session.workdir)).rejects.toThrow();
+    });
+
+    it('conflict keeps the worktree and writes a sentinel file', async () => {
+      const baseSha = await gitService.revParseHead();
+      if (!baseSha) {
+        throw new Error('no base sha');
+      }
+
+      const session = await sessionService.create('chat-cleanup-conflict', baseSha);
+      await sessionService.cleanup(session, 'conflict', { conflictPaths: ['shared.yaml'] });
+
+      // Dir still exists.
+      await expect(stat(session.workdir)).resolves.toBeTruthy();
+
+      const { readFile } = await import('node:fs/promises');
+      const raw = await readFile(join(session.workdir, '.ktx-outcome'), 'utf-8');
+      const parsed = JSON.parse(raw);
+      expect(parsed.outcome).toBe('conflict');
+      expect(parsed.chatId).toBe('chat-cleanup-conflict');
+      expect(parsed.conflictPaths).toEqual(['shared.yaml']);
+      expect(typeof parsed.at).toBe('string');
+    });
+  });
+});