bugfix

internal/codeindex/build_runner.go

@@ -0,0 +1,191 @@
+package codeindex
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+
+	"github.com/yan1h/agent-coding-workflow/internal/infra/git"
+	"github.com/yan1h/agent-coding-workflow/internal/infra/llm"
+	"github.com/yan1h/agent-coding-workflow/internal/jobs"
+)
+
+// EmbedBatchSize bounds how many chunks are sent to the embedder per request.
+const EmbedBatchSize = 64
+
+// FailureNotifier is an optional best-effort callback invoked when a build run
+// fails, so app.go can broadcast to admins without the runner importing user/notify.
+type FailureNotifier func(ctx context.Context, run *Run, cause error)
+
+// BuildRunner is the jobs.Handler that materializes a code_index_runs row into
+// embedded code_chunks. It is event-driven (enqueued by EnqueueBuild), never a
+// periodic ticker. Idempotent: re-running for the same run replaces its chunks.
+type BuildRunner struct {
+	repo     Repository
+	locator  WorkspaceLocator
+	gitr     git.Runner
+	embedSel EmbedderSelector
+	chunker  *Chunker
+	notify   FailureNotifier
+	log      *slog.Logger
+}
+
+// NewBuildRunner constructs a BuildRunner. notify and log may be nil.
+func NewBuildRunner(repo Repository, locator WorkspaceLocator, gitr git.Runner, embedSel EmbedderSelector, chunker *Chunker, notify FailureNotifier, log *slog.Logger) *BuildRunner {
+	if chunker == nil {
+		chunker = NewChunker()
+	}
+	if log == nil {
+		log = slog.Default()
+	}
+	return &BuildRunner{repo: repo, locator: locator, gitr: gitr, embedSel: embedSel, chunker: chunker, notify: notify, log: log}
+}
+
+var _ jobs.Handler = (*BuildRunner)(nil)
+
+// Type returns the job type this handler processes.
+func (h *BuildRunner) Type() jobs.JobType { return JobTypeBuild }
+
+// Handle builds the index for the run referenced in the payload. On any error it
+// marks the run failed and notifies admins; the returned error drives jobs retry.
+func (h *BuildRunner) Handle(ctx context.Context, job jobs.Job) error {
+	var p buildPayload
+	if err := json.Unmarshal(job.Payload, &p); err != nil {
+		return jobs.Permanent(fmt.Errorf("codeindex.build: bad payload: %w", err))
+	}
+	run, err := h.repo.GetRun(ctx, p.RunID)
+	if err != nil {
+		return jobs.Permanent(fmt.Errorf("codeindex.build: load run %s: %w", p.RunID, err))
+	}
+	// Skip runs superseded by a newer one (stale) — no-op success.
+	if run.Status == StatusStale || run.Status == StatusCompleted {
+		return nil
+	}
+
+	if err := h.build(ctx, run); err != nil {
+		if markErr := h.repo.MarkFailed(ctx, run.ID, truncErr(err)); markErr != nil {
+			h.log.Error("codeindex.build.mark_failed", "run_id", run.ID, "err", markErr.Error())
+		}
+		if h.notify != nil {
+			h.notify(ctx, run, err)
+		}
+		return err // retryable unless wrapped Permanent inside build
+	}
+	return nil
+}
+
+func (h *BuildRunner) build(ctx context.Context, run *Run) error {
+	emb, _, model, dims, err := h.embedSel.Embedder(ctx)
+	if err != nil {
+		return jobs.Permanent(fmt.Errorf("codeindex.build: embedder unavailable: %w", err))
+	}
+	// Validate dims match the fixed pgvector column to avoid corrupt inserts.
+	if d := emb.EmbedDims(model); d != 0 && d != llm.PlatformEmbeddingDims {
+		return jobs.Permanent(fmt.Errorf("codeindex.build: embedder dims %d != platform %d", d, llm.PlatformEmbeddingDims))
+	}
+	if dims != llm.PlatformEmbeddingDims {
+		return jobs.Permanent(fmt.Errorf("codeindex.build: run dims %d != platform %d", dims, llm.PlatformEmbeddingDims))
+	}
+
+	// Resolve the worktree/main directory holding the commit's files.
+	dir := ""
+	if run.WorktreeID != nil {
+		path, _, _, lerr := h.locator.LocateWorktree(ctx, *run.WorktreeID)
+		if lerr != nil {
+			return fmt.Errorf("locate worktree: %w", lerr)
+		}
+		dir = path
+	} else {
+		info, lerr := h.locator.LocateWorkspace(ctx, run.WorkspaceID)
+		if lerr != nil {
+			return fmt.Errorf("locate workspace: %w", lerr)
+		}
+		dir = info.MainPath
+	}
+
+	if err := h.repo.MarkRunning(ctx, run.ID); err != nil {
+		return fmt.Errorf("mark running: %w", err)
+	}
+
+	files, err := h.gitr.ListTrackedFiles(ctx, dir)
+	if err != nil {
+		return fmt.Errorf("git ls-files: %w", err)
+	}
+
+	var rows []ChunkRow
+	filesIndexed := 0
+	for _, rel := range files {
+		abs := filepath.Join(dir, filepath.FromSlash(rel))
+		fi, serr := os.Stat(abs)
+		if serr != nil || fi.IsDir() {
+			continue
+		}
+		if int(fi.Size()) > h.chunker.maxFileBytes() || isVendored(rel) {
+			continue
+		}
+		content, rerr := os.ReadFile(abs)
+		if rerr != nil {
+			continue
+		}
+		chunks := h.chunker.Chunk(rel, content)
+		if len(chunks) == 0 {
+			continue
+		}
+		filesIndexed++
+		for _, c := range chunks {
+			rows = append(rows, ChunkRow{
+				FilePath:   rel,
+				Lang:       c.Lang,
+				StartLine:  c.StartLine,
+				EndLine:    c.EndLine,
+				Content:    c.Content,
+				ContentSHA: c.ContentSHA,
+				TokenCount: llm.EstimateTokens(c.Content),
+			})
+		}
+	}
+
+	// Batch-embed chunk contents (input order preserved per batch).
+	for start := 0; start < len(rows); start += EmbedBatchSize {
+		end := start + EmbedBatchSize
+		if end > len(rows) {
+			end = len(rows)
+		}
+		inputs := make([]string, 0, end-start)
+		for i := start; i < end; i++ {
+			inputs = append(inputs, rows[i].Content)
+		}
+		vecs, eerr := emb.Embed(ctx, model, inputs)
+		if eerr != nil {
+			return fmt.Errorf("embed batch [%d:%d]: %w", start, end, eerr)
+		}
+		if len(vecs) != end-start {
+			return fmt.Errorf("embed batch [%d:%d]: got %d vectors", start, end, len(vecs))
+		}
+		for i := start; i < end; i++ {
+			rows[i].Embedding = vecs[i-start]
+		}
+	}
+
+	if err := h.repo.ReplaceChunks(ctx, run.ID, run.WorkspaceID, run.CommitSHA, rows); err != nil {
+		return fmt.Errorf("insert chunks: %w", err)
+	}
+	if err := h.repo.MarkCompleted(ctx, run.ID, filesIndexed, len(rows)); err != nil {
+		return fmt.Errorf("mark completed: %w", err)
+	}
+	h.log.Info("codeindex.build.completed",
+		"run_id", run.ID, "workspace_id", run.WorkspaceID, "commit", run.CommitSHA,
+		"files", filesIndexed, "chunks", len(rows))
+	return nil
+}
+
+func truncErr(err error) string {
+	s := err.Error()
+	if len(s) > 1000 {
+		return s[:1000]
+	}
+	return s
+}

internal/codeindex/build_runner_test.go

@@ -0,0 +1,213 @@
+package codeindex
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/require"
+
+	"github.com/yan1h/agent-coding-workflow/internal/infra/git"
+	"github.com/yan1h/agent-coding-workflow/internal/infra/llm"
+	"github.com/yan1h/agent-coding-workflow/internal/jobs"
+)
+
+// ===== fakes =====
+
+type fakeRepo struct {
+	runs      map[uuid.UUID]*Run
+	replaced  map[uuid.UUID][]ChunkRow
+	completed map[uuid.UUID]bool
+	failed    map[uuid.UUID]string
+	running   map[uuid.UUID]bool
+}
+
+func newFakeRepo() *fakeRepo {
+	return &fakeRepo{
+		runs: map[uuid.UUID]*Run{}, replaced: map[uuid.UUID][]ChunkRow{},
+		completed: map[uuid.UUID]bool{}, failed: map[uuid.UUID]string{}, running: map[uuid.UUID]bool{},
+	}
+}
+
+func (r *fakeRepo) InsertRun(_ context.Context, run *Run) (*Run, error) {
+	cp := *run
+	r.runs[run.ID] = &cp
+	return &cp, nil
+}
+func (r *fakeRepo) GetRun(_ context.Context, id uuid.UUID) (*Run, error) {
+	run, ok := r.runs[id]
+	if !ok {
+		return nil, errors.New("not found")
+	}
+	cp := *run
+	return &cp, nil
+}
+func (r *fakeRepo) GetRunByCommit(_ context.Context, wsID uuid.UUID, commit, model string) (*Run, error) {
+	for _, run := range r.runs {
+		if run.WorkspaceID == wsID && run.CommitSHA == commit && run.EmbeddingModel == model {
+			cp := *run
+			return &cp, nil
+		}
+	}
+	return nil, nil
+}
+func (r *fakeRepo) GetLatestCompletedRun(_ context.Context, wsID uuid.UUID) (*Run, error) {
+	for _, run := range r.runs {
+		if run.WorkspaceID == wsID && run.Status == StatusCompleted {
+			cp := *run
+			return &cp, nil
+		}
+	}
+	return nil, nil
+}
+func (r *fakeRepo) MarkRunning(_ context.Context, id uuid.UUID) error {
+	r.running[id] = true
+	return nil
+}
+func (r *fakeRepo) MarkCompleted(_ context.Context, id uuid.UUID, files, chunks int) error {
+	r.completed[id] = true
+	if run := r.runs[id]; run != nil {
+		run.Status = StatusCompleted
+		run.FilesIndexed = files
+		run.ChunksIndexed = chunks
+	}
+	return nil
+}
+func (r *fakeRepo) MarkFailed(_ context.Context, id uuid.UUID, msg string) error {
+	r.failed[id] = msg
+	if run := r.runs[id]; run != nil {
+		run.Status = StatusFailed
+	}
+	return nil
+}
+func (r *fakeRepo) MarkStale(_ context.Context, _ uuid.UUID) error { return nil }
+func (r *fakeRepo) MarkStuckStale(_ context.Context, _ time.Time) ([]uuid.UUID, error) {
+	return nil, nil
+}
+func (r *fakeRepo) ReplaceChunks(_ context.Context, runID, _ uuid.UUID, _ string, rows []ChunkRow) error {
+	r.replaced[runID] = rows
+	return nil
+}
+func (r *fakeRepo) SearchKNN(context.Context, uuid.UUID, []float32, int, string, string) ([]Snippet, error) {
+	return nil, nil
+}
+
+type fakeLocator struct {
+	dir  string
+	wsID uuid.UUID
+}
+
+func (l fakeLocator) LocateWorkspace(context.Context, uuid.UUID) (WorkspaceInfo, error) {
+	return WorkspaceInfo{ID: l.wsID, MainPath: l.dir, DefaultBranch: "main"}, nil
+}
+func (l fakeLocator) LocateWorktree(context.Context, uuid.UUID) (string, string, uuid.UUID, error) {
+	return l.dir, "main", l.wsID, nil
+}
+
+type fakeEmbedSel struct {
+	emb llm.Embedder
+	err error
+}
+
+func (s fakeEmbedSel) Embedder(context.Context) (llm.Embedder, uuid.UUID, string, int, error) {
+	if s.err != nil {
+		return nil, uuid.Nil, "", 0, s.err
+	}
+	return s.emb, uuid.New(), "fake-model", llm.PlatformEmbeddingDims, nil
+}
+
+func mustGit(t *testing.T, dir string, args ...string) {
+	t.Helper()
+	c := exec.Command("git", args...)
+	c.Dir = dir
+	out, err := c.CombinedOutput()
+	require.NoError(t, err, "git %v: %s", args, string(out))
+}
+
+func tempGitRepo(t *testing.T) (dir, sha string) {
+	t.Helper()
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not in PATH")
+	}
+	dir = t.TempDir()
+	mustGit(t, dir, "init", "-b", "main")
+	mustGit(t, dir, "config", "user.email", "t@e.com")
+	mustGit(t, dir, "config", "user.name", "T")
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "main.go"), []byte("package main\n\nfunc main() {}\n"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "util.go"), []byte("package main\n\nfunc add(a, b int) int { return a + b }\n"), 0o644))
+	mustGit(t, dir, "add", ".")
+	mustGit(t, dir, "commit", "-m", "init")
+	out, err := exec.Command("git", "-C", dir, "rev-parse", "HEAD").Output()
+	require.NoError(t, err)
+	sha = string(out[:len(out)-1])
+	return dir, sha
+}
+
+func TestBuildRunner_Success(t *testing.T) {
+	dir, sha := tempGitRepo(t)
+	wsID := uuid.New()
+	repo := newFakeRepo()
+	run := &Run{
+		ID: uuid.New(), WorkspaceID: wsID, Branch: "main", CommitSHA: sha,
+		Status: StatusPending, EmbeddingModel: "fake-model", Dims: llm.PlatformEmbeddingDims,
+	}
+	repo.runs[run.ID] = run
+
+	gitr := git.NewDefaultRunner(git.DefaultConfig())
+	br := NewBuildRunner(repo, fakeLocator{dir: dir, wsID: wsID}, gitr,
+		fakeEmbedSel{emb: llm.NewFakeEmbedder()}, NewChunker(), nil, nil)
+
+	payload, _ := json.Marshal(buildPayload{RunID: run.ID})
+	err := br.Handle(context.Background(), jobs.Job{Payload: payload})
+	require.NoError(t, err)
+	require.True(t, repo.completed[run.ID])
+	require.True(t, repo.running[run.ID])
+	require.NotEmpty(t, repo.replaced[run.ID], "chunks must be inserted")
+	// Each inserted row must carry an embedding of platform dims.
+	for _, row := range repo.replaced[run.ID] {
+		require.Len(t, row.Embedding, llm.PlatformEmbeddingDims)
+	}
+}
+
+func TestBuildRunner_FailureMarksFailedAndNotifies(t *testing.T) {
+	dir, sha := tempGitRepo(t)
+	wsID := uuid.New()
+	repo := newFakeRepo()
+	run := &Run{
+		ID: uuid.New(), WorkspaceID: wsID, Branch: "main", CommitSHA: sha,
+		Status: StatusPending, EmbeddingModel: "fake-model", Dims: llm.PlatformEmbeddingDims,
+	}
+	repo.runs[run.ID] = run
+
+	embErr := errors.New("embed boom")
+	notified := false
+	gitr := git.NewDefaultRunner(git.DefaultConfig())
+	br := NewBuildRunner(repo, fakeLocator{dir: dir, wsID: wsID}, gitr,
+		fakeEmbedSel{emb: &llm.FakeEmbedder{Dims: llm.PlatformEmbeddingDims, Err: embErr}},
+		NewChunker(),
+		func(context.Context, *Run, error) { notified = true }, nil)
+
+	payload, _ := json.Marshal(buildPayload{RunID: run.ID})
+	err := br.Handle(context.Background(), jobs.Job{Payload: payload})
+	require.Error(t, err)
+	require.Contains(t, repo.failed[run.ID], "embed boom")
+	require.True(t, notified)
+}
+
+func TestBuildRunner_SkipsAlreadyCompleted(t *testing.T) {
+	repo := newFakeRepo()
+	run := &Run{ID: uuid.New(), Status: StatusCompleted, EmbeddingModel: "fake-model", Dims: llm.PlatformEmbeddingDims}
+	repo.runs[run.ID] = run
+	br := NewBuildRunner(repo, fakeLocator{}, nil, fakeEmbedSel{emb: llm.NewFakeEmbedder()}, NewChunker(), nil, nil)
+	payload, _ := json.Marshal(buildPayload{RunID: run.ID})
+	require.NoError(t, br.Handle(context.Background(), jobs.Job{Payload: payload}))
+	require.Empty(t, repo.replaced[run.ID])
+}
+
+var _ Repository = (*fakeRepo)(nil)

internal/codeindex/chunker.go

@@ -0,0 +1,216 @@
+package codeindex
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"path/filepath"
+	"strings"
+
+	"github.com/yan1h/agent-coding-workflow/internal/infra/llm"
+)
+
+// Chunker config defaults. Windows are line-based; the token cap (estimated via
+// llm.EstimateTokens) hard-bounds embedding cost on pathological long lines.
+const (
+	DefaultWindowLines    = 60
+	DefaultOverlapLines   = 10
+	DefaultMaxFileBytes   = 512 * 1024 // skip files larger than this
+	DefaultMaxChunkTokens = 1024       // estimated; oversize windows are truncated
+)
+
+// Chunker splits file content into overlapping line windows.
+type Chunker struct {
+	WindowLines    int
+	OverlapLines   int
+	MaxFileBytes   int
+	MaxChunkTokens int
+}
+
+// NewChunker returns a Chunker with platform defaults.
+func NewChunker() *Chunker {
+	return &Chunker{
+		WindowLines:    DefaultWindowLines,
+		OverlapLines:   DefaultOverlapLines,
+		MaxFileBytes:   DefaultMaxFileBytes,
+		MaxChunkTokens: DefaultMaxChunkTokens,
+	}
+}
+
+func (c *Chunker) window() int {
+	if c.WindowLines > 0 {
+		return c.WindowLines
+	}
+	return DefaultWindowLines
+}
+
+func (c *Chunker) overlap() int {
+	if c.OverlapLines >= 0 && c.OverlapLines < c.window() {
+		return c.OverlapLines
+	}
+	return DefaultOverlapLines
+}
+
+func (c *Chunker) maxFileBytes() int {
+	if c.MaxFileBytes > 0 {
+		return c.MaxFileBytes
+	}
+	return DefaultMaxFileBytes
+}
+
+func (c *Chunker) maxChunkTokens() int {
+	if c.MaxChunkTokens > 0 {
+		return c.MaxChunkTokens
+	}
+	return DefaultMaxChunkTokens
+}
+
+// Skippable reports whether a file should not be indexed (binary, oversize, or
+// vendored). Callers should check this before reading large files.
+func (c *Chunker) Skippable(filePath string, size int, content []byte) bool {
+	if size > c.maxFileBytes() {
+		return true
+	}
+	if isVendored(filePath) {
+		return true
+	}
+	if isBinary(content) {
+		return true
+	}
+	return false
+}
+
+// Chunk splits content into overlapping line windows. Returns nil for skippable
+// or empty input. ContentSHA is the sha256 of the chunk's exact content so the
+// build runner can reuse already-embedded chunks across commits.
+func (c *Chunker) Chunk(filePath string, content []byte) []Chunk {
+	if len(content) == 0 {
+		return nil
+	}
+	if c.Skippable(filePath, len(content), content) {
+		return nil
+	}
+	lines := strings.Split(string(content), "\n")
+	// Drop a trailing empty element from a final newline so end_line is accurate.
+	if n := len(lines); n > 0 && lines[n-1] == "" {
+		lines = lines[:n-1]
+	}
+	if len(lines) == 0 {
+		return nil
+	}
+	lang := langForPath(filePath)
+	window := c.window()
+	step := window - c.overlap()
+	if step <= 0 {
+		step = window
+	}
+	maxTok := c.maxChunkTokens()
+
+	var out []Chunk
+	for start := 0; start < len(lines); start += step {
+		end := start + window
+		if end > len(lines) {
+			end = len(lines)
+		}
+		body := strings.Join(lines[start:end], "\n")
+		// Hard token cap: truncate runaway windows (minified/one-line files).
+		if llm.EstimateTokens(body) > maxTok {
+			body = truncateToTokens(body, maxTok)
+		}
+		sum := sha256.Sum256([]byte(body))
+		out = append(out, Chunk{
+			StartLine:  start + 1, // 1-based, inclusive
+			EndLine:    end,       // 1-based, inclusive
+			Lang:       lang,
+			Content:    body,
+			ContentSHA: sum[:],
+		})
+		if end == len(lines) {
+			break
+		}
+	}
+	return out
+}
+
+// truncateToTokens cuts s down to roughly maxTok estimated tokens (4 chars/token).
+func truncateToTokens(s string, maxTok int) string {
+	maxBytes := maxTok * 4
+	if len(s) <= maxBytes {
+		return s
+	}
+	// Cut on a UTF-8 boundary.
+	for maxBytes > 0 && (s[maxBytes]&0xC0) == 0x80 {
+		maxBytes--
+	}
+	return s[:maxBytes]
+}
+
+// isBinary reports whether content looks binary (NUL byte in the first 8KB).
+func isBinary(content []byte) bool {
+	n := len(content)
+	if n > 8192 {
+		n = 8192
+	}
+	return bytes.IndexByte(content[:n], 0) >= 0
+}
+
+// vendoredDirs are path segments whose contents are excluded from the index.
+var vendoredDirs = []string{
+	"vendor/", "node_modules/", ".git/", "dist/", "build/", "third_party/",
+	"testdata/", ".venv/", "__pycache__/",
+}
+
+func isVendored(p string) bool {
+	norm := filepath.ToSlash(p)
+	for _, d := range vendoredDirs {
+		if strings.HasPrefix(norm, d) || strings.Contains(norm, "/"+d) {
+			return true
+		}
+	}
+	return false
+}
+
+// langForPath maps a file extension to a coarse language label (best-effort).
+func langForPath(p string) string {
+	switch strings.ToLower(filepath.Ext(p)) {
+	case ".go":
+		return "go"
+	case ".ts", ".tsx":
+		return "typescript"
+	case ".js", ".jsx", ".mjs", ".cjs":
+		return "javascript"
+	case ".vue":
+		return "vue"
+	case ".py":
+		return "python"
+	case ".rs":
+		return "rust"
+	case ".java":
+		return "java"
+	case ".c", ".h":
+		return "c"
+	case ".cpp", ".cc", ".hpp":
+		return "cpp"
+	case ".rb":
+		return "ruby"
+	case ".php":
+		return "php"
+	case ".sql":
+		return "sql"
+	case ".sh", ".bash":
+		return "shell"
+	case ".md", ".markdown":
+		return "markdown"
+	case ".json":
+		return "json"
+	case ".yaml", ".yml":
+		return "yaml"
+	case ".toml":
+		return "toml"
+	case ".html", ".htm":
+		return "html"
+	case ".css", ".scss":
+		return "css"
+	default:
+		return ""
+	}
+}

internal/codeindex/chunker_test.go

@@ -0,0 +1,91 @@
+package codeindex
+
+import (
+	"crypto/sha256"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestChunker_WindowsAndLineNumbers(t *testing.T) {
+	c := &Chunker{WindowLines: 10, OverlapLines: 2, MaxFileBytes: 1 << 20, MaxChunkTokens: 10000}
+	// 25 numbered lines.
+	var sb strings.Builder
+	for i := 1; i <= 25; i++ {
+		sb.WriteString("line")
+		sb.WriteByte(byte('0' + i%10))
+		sb.WriteByte('\n')
+	}
+	chunks := c.Chunk("a.go", []byte(sb.String()))
+	require.NotEmpty(t, chunks)
+
+	// First window: lines 1..10.
+	require.Equal(t, 1, chunks[0].StartLine)
+	require.Equal(t, 10, chunks[0].EndLine)
+	require.Equal(t, "go", chunks[0].Lang)
+
+	// step = window - overlap = 8 → next window starts at line 9.
+	require.Equal(t, 9, chunks[1].StartLine)
+	require.Equal(t, 18, chunks[1].EndLine)
+
+	// Last chunk must end exactly at line 25.
+	last := chunks[len(chunks)-1]
+	require.Equal(t, 25, last.EndLine)
+}
+
+func TestChunker_ContentSHAStable(t *testing.T) {
+	c := NewChunker()
+	content := []byte("package x\n\nfunc Y() {}\n")
+	a := c.Chunk("x.go", content)
+	b := c.Chunk("x.go", content)
+	require.Equal(t, len(a), len(b))
+	require.Equal(t, a[0].ContentSHA, b[0].ContentSHA)
+	// SHA must be sha256 of the chunk content.
+	sum := sha256.Sum256([]byte(a[0].Content))
+	require.Equal(t, sum[:], a[0].ContentSHA)
+}
+
+func TestChunker_SkipsBinary(t *testing.T) {
+	c := NewChunker()
+	bin := []byte("text\x00more\x00binary")
+	require.Nil(t, c.Chunk("data.bin", bin))
+	require.True(t, c.Skippable("data.bin", len(bin), bin))
+}
+
+func TestChunker_SkipsOversize(t *testing.T) {
+	c := &Chunker{WindowLines: 10, MaxFileBytes: 8}
+	big := []byte("aaaaaaaaaaaaaaaaaaaa\n") // > 8 bytes
+	require.Nil(t, c.Chunk("big.txt", big))
+}
+
+func TestChunker_SkipsVendored(t *testing.T) {
+	c := NewChunker()
+	content := []byte("package vendored\n")
+	require.Nil(t, c.Chunk("vendor/foo/bar.go", content))
+	require.Nil(t, c.Chunk("node_modules/pkg/index.js", content))
+	require.True(t, isVendored("a/b/node_modules/x.js"))
+	require.False(t, isVendored("internal/codeindex/chunker.go"))
+}
+
+func TestChunker_EmptyInput(t *testing.T) {
+	c := NewChunker()
+	require.Nil(t, c.Chunk("e.go", nil))
+	require.Nil(t, c.Chunk("e.go", []byte("")))
+}
+
+func TestChunker_TokenCapTruncates(t *testing.T) {
+	// One very long line that exceeds the token cap is truncated.
+	c := &Chunker{WindowLines: 60, OverlapLines: 10, MaxFileBytes: 1 << 20, MaxChunkTokens: 5}
+	long := strings.Repeat("x", 1000)
+	chunks := c.Chunk("min.js", []byte(long+"\n"))
+	require.Len(t, chunks, 1)
+	require.LessOrEqual(t, len(chunks[0].Content), 5*4) // ~maxTok*4 bytes
+}
+
+func TestLangForPath(t *testing.T) {
+	require.Equal(t, "go", langForPath("a/b.go"))
+	require.Equal(t, "typescript", langForPath("c.tsx"))
+	require.Equal(t, "python", langForPath("x.py"))
+	require.Equal(t, "", langForPath("Makefile"))
+}

internal/codeindex/domain.go

@@ -0,0 +1,75 @@
+// Package codeindex builds and queries a pgvector-backed code index keyed by
+// (workspace, commit). A background job (BuildRunner) embeds git-tracked file
+// chunks; the Search path runs cosine-KNN scoped to the latest completed run.
+// When no embedding endpoint is configured the whole feature is disabled with a
+// typed error (callers degrade to keyword discovery via fs/grep).
+package codeindex
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+
+	"github.com/yan1h/agent-coding-workflow/internal/jobs"
+)
+
+// JobTypeBuild is the jobs.JobType for an event-driven index build.
+const JobTypeBuild jobs.JobType = "codeindex.build"
+
+// Run status values mirror the code_index_runs.status CHECK constraint.
+const (
+	StatusPending   = "pending"
+	StatusRunning   = "running"
+	StatusCompleted = "completed"
+	StatusFailed    = "failed"
+	StatusStale     = "stale"
+)
+
+// Run mirrors a code_index_runs row.
+type Run struct {
+	ID                  uuid.UUID
+	WorkspaceID         uuid.UUID
+	WorktreeID          *uuid.UUID
+	Branch              string
+	CommitSHA           string
+	Status              string
+	EmbeddingEndpointID *uuid.UUID
+	EmbeddingModel      string
+	Dims                int
+	FilesIndexed        int
+	ChunksIndexed       int
+	Error               *string
+	CreatedAt           time.Time
+}
+
+// Chunk is one embeddable line window produced by the Chunker.
+type Chunk struct {
+	StartLine  int
+	EndLine    int
+	Lang       string
+	Content    string
+	ContentSHA []byte // sha256 of Content; enables incremental re-embed
+}
+
+// Snippet is a ranked search result returned to callers (MCP search_code).
+type Snippet struct {
+	FilePath  string
+	StartLine int
+	EndLine   int
+	Content   string
+	Score     float32 // cosine similarity in [0,1]; higher is closer
+	CommitSHA string
+}
+
+// SearchQuery parameterizes a code search.
+type SearchQuery struct {
+	Text       string
+	TopK       int
+	PathPrefix string
+	Lang       string
+}
+
+// buildPayload is the jobs payload for JobTypeBuild.
+type buildPayload struct {
+	RunID uuid.UUID `json:"run_id"`
+}

internal/codeindex/queries/chunks.sql

@@ -0,0 +1,9 @@
+-- The embedding (vector) column is intentionally excluded from every sqlc query
+-- here: sqlc has no native pgvector type. Vector INSERT (bulk) and cosine-KNN
+-- SELECT are hand-written in repository.go using the pgvector text literal format.
+
+-- name: DeleteChunksByRun :exec
+DELETE FROM code_chunks WHERE run_id = $1;
+
+-- name: CountChunksByRun :one
+SELECT count(*) FROM code_chunks WHERE run_id = $1;

internal/codeindex/queries/runs.sql

@@ -0,0 +1,58 @@
+-- name: InsertRun :one
+INSERT INTO code_index_runs (
+  id, workspace_id, worktree_id, branch, commit_sha, status,
+  embedding_endpoint_id, embedding_model, dims
+) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+RETURNING id, workspace_id, worktree_id, branch, commit_sha, status,
+          embedding_endpoint_id, embedding_model, dims,
+          files_indexed, chunks_indexed, error, started_at, finished_at, created_at;
+
+-- name: GetRun :one
+SELECT id, workspace_id, worktree_id, branch, commit_sha, status,
+       embedding_endpoint_id, embedding_model, dims,
+       files_indexed, chunks_indexed, error, started_at, finished_at, created_at
+FROM code_index_runs
+WHERE id = $1;
+
+-- name: GetRunByCommit :one
+SELECT id, workspace_id, worktree_id, branch, commit_sha, status,
+       embedding_endpoint_id, embedding_model, dims,
+       files_indexed, chunks_indexed, error, started_at, finished_at, created_at
+FROM code_index_runs
+WHERE workspace_id = $1 AND commit_sha = $2 AND embedding_model = $3;
+
+-- name: GetLatestCompletedRun :one
+SELECT id, workspace_id, worktree_id, branch, commit_sha, status,
+       embedding_endpoint_id, embedding_model, dims,
+       files_indexed, chunks_indexed, error, started_at, finished_at, created_at
+FROM code_index_runs
+WHERE workspace_id = $1 AND status = 'completed'
+ORDER BY created_at DESC
+LIMIT 1;
+
+-- name: MarkRunRunning :exec
+UPDATE code_index_runs
+SET status = 'running', started_at = now()
+WHERE id = $1;
+
+-- name: MarkRunCompleted :exec
+UPDATE code_index_runs
+SET status = 'completed', files_indexed = $2, chunks_indexed = $3,
+    error = NULL, finished_at = now()
+WHERE id = $1;
+
+-- name: MarkRunFailed :exec
+UPDATE code_index_runs
+SET status = 'failed', error = $2, finished_at = now()
+WHERE id = $1;
+
+-- name: MarkRunsStale :exec
+UPDATE code_index_runs
+SET status = 'stale'
+WHERE workspace_id = $1 AND status IN ('pending','running','completed');
+
+-- name: MarkStuckRunsStale :many
+UPDATE code_index_runs
+SET status = 'stale'
+WHERE status = 'running' AND started_at < $1
+RETURNING id;

internal/codeindex/repository.go

@@ -0,0 +1,294 @@
+package codeindex
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/pgvector/pgvector-go"
+
+	codeindexsqlc "github.com/yan1h/agent-coding-workflow/internal/codeindex/sqlc"
+	"github.com/yan1h/agent-coding-workflow/internal/infra/errs"
+)
+
+// ChunkRow is a fully-populated chunk ready for bulk insert (embedding included).
+type ChunkRow struct {
+	FilePath   string
+	Lang       string
+	StartLine  int
+	EndLine    int
+	Content    string
+	ContentSHA []byte
+	TokenCount int
+	Embedding  []float32
+}
+
+// Repository is the codeindex persistence contract.
+type Repository interface {
+	InsertRun(ctx context.Context, r *Run) (*Run, error)
+	GetRun(ctx context.Context, id uuid.UUID) (*Run, error)
+	GetRunByCommit(ctx context.Context, wsID uuid.UUID, commitSHA, model string) (*Run, error)
+	GetLatestCompletedRun(ctx context.Context, wsID uuid.UUID) (*Run, error)
+	MarkRunning(ctx context.Context, id uuid.UUID) error
+	MarkCompleted(ctx context.Context, id uuid.UUID, files, chunks int) error
+	MarkFailed(ctx context.Context, id uuid.UUID, errMsg string) error
+	MarkStale(ctx context.Context, wsID uuid.UUID) error
+	MarkStuckStale(ctx context.Context, runningBefore time.Time) ([]uuid.UUID, error)
+	// ReplaceChunks deletes any existing chunks for run then bulk-inserts rows.
+	ReplaceChunks(ctx context.Context, runID, wsID uuid.UUID, commitSHA string, rows []ChunkRow) error
+	// SearchKNN returns the top-k chunks of the latest completed run for wsID
+	// ordered by cosine similarity to queryVec, with optional path/lang filters.
+	SearchKNN(ctx context.Context, wsID uuid.UUID, queryVec []float32, topK int, pathPrefix, lang string) ([]Snippet, error)
+}
+
+// PgRepository is the production Repository on a pgxpool.Pool.
+type PgRepository struct {
+	pool *pgxpool.Pool
+	q    *codeindexsqlc.Queries
+}
+
+// NewPostgresRepository builds a PgRepository.
+func NewPostgresRepository(pool *pgxpool.Pool) *PgRepository {
+	return &PgRepository{pool: pool, q: codeindexsqlc.New(pool)}
+}
+
+var _ Repository = (*PgRepository)(nil)
+
+func pgUUID(u uuid.UUID) pgtype.UUID { return pgtype.UUID{Bytes: u, Valid: true} }
+
+func pgUUIDPtr(u *uuid.UUID) pgtype.UUID {
+	if u == nil {
+		return pgtype.UUID{}
+	}
+	return pgtype.UUID{Bytes: *u, Valid: true}
+}
+
+func uuidPtr(p pgtype.UUID) *uuid.UUID {
+	if !p.Valid {
+		return nil
+	}
+	id := uuid.UUID(p.Bytes)
+	return &id
+}
+
+func runFromRow(r codeindexsqlc.CodeIndexRun) *Run {
+	out := &Run{
+		ID:                  uuid.UUID(r.ID.Bytes),
+		WorkspaceID:         uuid.UUID(r.WorkspaceID.Bytes),
+		WorktreeID:          uuidPtr(r.WorktreeID),
+		Branch:              r.Branch,
+		CommitSHA:           r.CommitSha,
+		Status:              r.Status,
+		EmbeddingEndpointID: uuidPtr(r.EmbeddingEndpointID),
+		EmbeddingModel:      r.EmbeddingModel,
+		Dims:                int(r.Dims),
+		FilesIndexed:        int(r.FilesIndexed),
+		ChunksIndexed:       int(r.ChunksIndexed),
+		Error:               r.Error,
+	}
+	if r.CreatedAt.Valid {
+		out.CreatedAt = r.CreatedAt.Time
+	}
+	return out
+}
+
+func (r *PgRepository) InsertRun(ctx context.Context, run *Run) (*Run, error) {
+	row, err := r.q.InsertRun(ctx, codeindexsqlc.InsertRunParams{
+		ID:                  pgUUID(run.ID),
+		WorkspaceID:         pgUUID(run.WorkspaceID),
+		WorktreeID:          pgUUIDPtr(run.WorktreeID),
+		Branch:              run.Branch,
+		CommitSha:           run.CommitSHA,
+		Status:              StatusPending,
+		EmbeddingEndpointID: pgUUIDPtr(run.EmbeddingEndpointID),
+		EmbeddingModel:      run.EmbeddingModel,
+		Dims:                int32(run.Dims),
+	})
+	if err != nil {
+		return nil, errs.Wrap(err, errs.CodeInternal, "insert code index run")
+	}
+	return runFromRow(row), nil
+}
+
+func (r *PgRepository) GetRun(ctx context.Context, id uuid.UUID) (*Run, error) {
+	row, err := r.q.GetRun(ctx, pgUUID(id))
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, errs.New(errs.CodeNotFound, "code index run not found")
+		}
+		return nil, errs.Wrap(err, errs.CodeInternal, "get code index run")
+	}
+	return runFromRow(row), nil
+}
+
+func (r *PgRepository) GetRunByCommit(ctx context.Context, wsID uuid.UUID, commitSHA, model string) (*Run, error) {
+	row, err := r.q.GetRunByCommit(ctx, codeindexsqlc.GetRunByCommitParams{
+		WorkspaceID:    pgUUID(wsID),
+		CommitSha:      commitSHA,
+		EmbeddingModel: model,
+	})
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+		return nil, errs.Wrap(err, errs.CodeInternal, "get run by commit")
+	}
+	return runFromRow(row), nil
+}
+
+func (r *PgRepository) GetLatestCompletedRun(ctx context.Context, wsID uuid.UUID) (*Run, error) {
+	row, err := r.q.GetLatestCompletedRun(ctx, pgUUID(wsID))
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+		return nil, errs.Wrap(err, errs.CodeInternal, "get latest completed run")
+	}
+	return runFromRow(row), nil
+}
+
+func (r *PgRepository) MarkRunning(ctx context.Context, id uuid.UUID) error {
+	if err := r.q.MarkRunRunning(ctx, pgUUID(id)); err != nil {
+		return errs.Wrap(err, errs.CodeInternal, "mark run running")
+	}
+	return nil
+}
+
+func (r *PgRepository) MarkCompleted(ctx context.Context, id uuid.UUID, files, chunks int) error {
+	if err := r.q.MarkRunCompleted(ctx, codeindexsqlc.MarkRunCompletedParams{
+		ID:            pgUUID(id),
+		FilesIndexed:  int32(files),
+		ChunksIndexed: int32(chunks),
+	}); err != nil {
+		return errs.Wrap(err, errs.CodeInternal, "mark run completed")
+	}
+	return nil
+}
+
+func (r *PgRepository) MarkFailed(ctx context.Context, id uuid.UUID, errMsg string) error {
+	msg := errMsg
+	if err := r.q.MarkRunFailed(ctx, codeindexsqlc.MarkRunFailedParams{
+		ID:    pgUUID(id),
+		Error: &msg,
+	}); err != nil {
+		return errs.Wrap(err, errs.CodeInternal, "mark run failed")
+	}
+	return nil
+}
+
+func (r *PgRepository) MarkStale(ctx context.Context, wsID uuid.UUID) error {
+	if err := r.q.MarkRunsStale(ctx, pgUUID(wsID)); err != nil {
+		return errs.Wrap(err, errs.CodeInternal, "mark runs stale")
+	}
+	return nil
+}
+
+func (r *PgRepository) MarkStuckStale(ctx context.Context, runningBefore time.Time) ([]uuid.UUID, error) {
+	rows, err := r.q.MarkStuckRunsStale(ctx, pgtype.Timestamptz{Time: runningBefore, Valid: true})
+	if err != nil {
+		return nil, errs.Wrap(err, errs.CodeInternal, "mark stuck runs stale")
+	}
+	out := make([]uuid.UUID, 0, len(rows))
+	for _, p := range rows {
+		out = append(out, uuid.UUID(p.Bytes))
+	}
+	return out, nil
+}
+
+// ReplaceChunks deletes prior chunks for the run and bulk-inserts the given rows
+// in a single transaction. The embedding column uses the pgvector text literal.
+func (r *PgRepository) ReplaceChunks(ctx context.Context, runID, wsID uuid.UUID, commitSHA string, rows []ChunkRow) error {
+	tx, err := r.pool.Begin(ctx)
+	if err != nil {
+		return errs.Wrap(err, errs.CodeInternal, "begin chunk tx")
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	if _, err := tx.Exec(ctx, `DELETE FROM code_chunks WHERE run_id = $1`, pgUUID(runID)); err != nil {
+		return errs.Wrap(err, errs.CodeInternal, "delete prior chunks")
+	}
+
+	const insertSQL = `INSERT INTO code_chunks (
+		id, run_id, workspace_id, commit_sha, file_path, lang,
+		start_line, end_line, content, content_sha, token_count, embedding
+	) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12::vector)`
+
+	batch := &pgx.Batch{}
+	for _, row := range rows {
+		var lang *string
+		if row.Lang != "" {
+			l := row.Lang
+			lang = &l
+		}
+		var tok *int32
+		if row.TokenCount > 0 {
+			t := int32(row.TokenCount)
+			tok = &t
+		}
+		batch.Queue(insertSQL,
+			pgUUID(uuid.New()), pgUUID(runID), pgUUID(wsID), commitSHA,
+			row.FilePath, lang, int32(row.StartLine), int32(row.EndLine),
+			row.Content, row.ContentSHA, tok, pgvector.NewVector(row.Embedding),
+		)
+	}
+	br := tx.SendBatch(ctx, batch)
+	for range rows {
+		if _, err := br.Exec(); err != nil {
+			_ = br.Close()
+			return errs.Wrap(err, errs.CodeInternal, "insert chunk")
+		}
+	}
+	if err := br.Close(); err != nil {
+		return errs.Wrap(err, errs.CodeInternal, "close chunk batch")
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return errs.Wrap(err, errs.CodeInternal, "commit chunk tx")
+	}
+	return nil
+}
+
+// SearchKNN runs cosine-distance KNN scoped to the latest completed run for the
+// workspace. Score is 1 - cosine_distance (so higher is more similar). Optional
+// path_prefix / lang filters narrow the candidate set.
+func (r *PgRepository) SearchKNN(ctx context.Context, wsID uuid.UUID, queryVec []float32, topK int, pathPrefix, lang string) ([]Snippet, error) {
+	if topK <= 0 {
+		topK = 10
+	}
+	q := `
+WITH latest AS (
+  SELECT id FROM code_index_runs
+  WHERE workspace_id = $1 AND status = 'completed'
+  ORDER BY created_at DESC LIMIT 1
+)
+SELECT c.file_path, c.start_line, c.end_line, c.content, c.commit_sha,
+       1 - (c.embedding <=> $2::vector) AS score
+FROM code_chunks c
+JOIN latest ON c.run_id = latest.id
+WHERE ($3::text = '' OR c.file_path LIKE $3 || '%')
+  AND ($4::text = '' OR c.lang = $4)
+ORDER BY c.embedding <=> $2::vector
+LIMIT $5`
+	rows, err := r.pool.Query(ctx, q, pgUUID(wsID), pgvector.NewVector(queryVec), pathPrefix, lang, int32(topK))
+	if err != nil {
+		return nil, errs.Wrap(err, errs.CodeInternal, "knn search")
+	}
+	defer rows.Close()
+	var out []Snippet
+	for rows.Next() {
+		var s Snippet
+		var start, end int32
+		if err := rows.Scan(&s.FilePath, &start, &end, &s.Content, &s.CommitSHA, &s.Score); err != nil {
+			return nil, errs.Wrap(err, errs.CodeInternal, "scan knn row")
+		}
+		s.StartLine, s.EndLine = int(start), int(end)
+		out = append(out, s)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, errs.Wrap(err, errs.CodeInternal, "knn rows")
+	}
+	return out, nil
+}

internal/codeindex/service.go

@@ -0,0 +1,195 @@
+package codeindex
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"time"
+
+	"github.com/google/uuid"
+
+	"github.com/yan1h/agent-coding-workflow/internal/infra/errs"
+	"github.com/yan1h/agent-coding-workflow/internal/infra/git"
+	"github.com/yan1h/agent-coding-workflow/internal/infra/llm"
+	"github.com/yan1h/agent-coding-workflow/internal/jobs"
+)
+
+// ErrEmbeddingDisabled is returned by Search/EnqueueBuild when no embedding
+// endpoint is configured. Callers degrade to keyword discovery (fs/grep) and
+// expose this as a typed, non-fatal "feature off" condition.
+var ErrEmbeddingDisabled = errors.New("codeindex: no embedding endpoint configured")
+
+// WorkspaceInfo is the minimal workspace data the indexer needs. Provided by a
+// locator implemented in app.go over the workspace repository (no import cycle).
+type WorkspaceInfo struct {
+	ID            uuid.UUID
+	MainPath      string
+	DefaultBranch string
+}
+
+// WorkspaceLocator resolves a workspace's on-disk path and default branch.
+type WorkspaceLocator interface {
+	LocateWorkspace(ctx context.Context, wsID uuid.UUID) (WorkspaceInfo, error)
+	// LocateWorktree resolves a worktree's on-disk path + branch (for branch builds).
+	LocateWorktree(ctx context.Context, worktreeID uuid.UUID) (path, branch string, wsID uuid.UUID, err error)
+}
+
+// EmbedderSelector resolves the configured platform embedder, or nil + a typed
+// error when embeddings are disabled (no endpoint configured / unsupported).
+type EmbedderSelector interface {
+	// Embedder returns the embedder, the embedding endpoint id, the model id and
+	// the platform dims. Returns ErrEmbeddingDisabled when not configured.
+	Embedder(ctx context.Context) (emb llm.Embedder, endpointID uuid.UUID, model string, dims int, err error)
+}
+
+// Enqueuer is the subset of jobs.Repository the service needs.
+type Enqueuer interface {
+	Enqueue(ctx context.Context, typ jobs.JobType, payload json.RawMessage, scheduledAt time.Time, maxAttempts int32) (*jobs.Job, error)
+}
+
+// Service is the codeindex application service.
+type Service interface {
+	// EnqueueBuild resolves the build commit (HEAD of the worktree/main) and
+	// enqueues a codeindex.build job. Idempotent on (workspace, commit, model):
+	// a re-enqueue at the same commit returns the existing run without rebuild.
+	EnqueueBuild(ctx context.Context, wsID uuid.UUID, worktreeID *uuid.UUID, commitSHA string) (*Run, error)
+	Search(ctx context.Context, wsID uuid.UUID, q SearchQuery) ([]Snippet, error)
+	MarkStale(ctx context.Context, wsID uuid.UUID) error
+}
+
+type service struct {
+	repo     Repository
+	locator  WorkspaceLocator
+	gitr     git.Runner
+	embedSel EmbedderSelector
+	jobs     Enqueuer
+	maxTopK  int
+}
+
+// NewService constructs the codeindex Service. maxTopK caps Search top_k.
+func NewService(repo Repository, locator WorkspaceLocator, gitr git.Runner, embedSel EmbedderSelector, jobsRepo Enqueuer, maxTopK int) Service {
+	if maxTopK <= 0 {
+		maxTopK = 50
+	}
+	return &service{repo: repo, locator: locator, gitr: gitr, embedSel: embedSel, jobs: jobsRepo, maxTopK: maxTopK}
+}
+
+func (s *service) EnqueueBuild(ctx context.Context, wsID uuid.UUID, worktreeID *uuid.UUID, commitSHA string) (*Run, error) {
+	emb, endpointID, model, dims, err := s.embedSel.Embedder(ctx)
+	if err != nil {
+		return nil, err // ErrEmbeddingDisabled or config error
+	}
+	_ = emb
+
+	branch := ""
+	dir := ""
+	if worktreeID != nil {
+		path, b, locWS, lerr := s.locator.LocateWorktree(ctx, *worktreeID)
+		if lerr != nil {
+			return nil, lerr
+		}
+		dir, branch, wsID = path, b, locWS
+	} else {
+		info, lerr := s.locator.LocateWorkspace(ctx, wsID)
+		if lerr != nil {
+			return nil, lerr
+		}
+		dir, branch = info.MainPath, info.DefaultBranch
+	}
+
+	// Resolve HEAD commit when not supplied.
+	if commitSHA == "" {
+		commits, lerr := s.gitr.Log(ctx, dir, 1)
+		if lerr != nil {
+			return nil, errs.Wrap(lerr, errs.CodeGitCmdFailed, "resolve HEAD")
+		}
+		if len(commits) == 0 {
+			return nil, errs.New(errs.CodeInvalidInput, "empty repository: no commit to index")
+		}
+		commitSHA = commits[0].Hash
+	}
+
+	// Idempotency: an existing run at this (ws, commit, model) is reused unless it
+	// previously failed/stale (in which case we re-enqueue against the same row).
+	existing, lerr := s.repo.GetRunByCommit(ctx, wsID, commitSHA, model)
+	if lerr != nil {
+		return nil, lerr
+	}
+	if existing != nil {
+		switch existing.Status {
+		case StatusPending, StatusRunning, StatusCompleted:
+			return existing, nil
+		}
+		// failed/stale: fall through and create a fresh run is blocked by UNIQUE;
+		// re-enqueue the existing run id instead.
+		if err := s.enqueueJob(ctx, existing.ID); err != nil {
+			return nil, err
+		}
+		return existing, nil
+	}
+
+	run := &Run{
+		ID:                  uuid.New(),
+		WorkspaceID:         wsID,
+		WorktreeID:          worktreeID,
+		Branch:              branch,
+		CommitSHA:           commitSHA,
+		Status:              StatusPending,
+		EmbeddingEndpointID: &endpointID,
+		EmbeddingModel:      model,
+		Dims:                dims,
+	}
+	saved, err := s.repo.InsertRun(ctx, run)
+	if err != nil {
+		return nil, err
+	}
+	if err := s.enqueueJob(ctx, saved.ID); err != nil {
+		return nil, err
+	}
+	return saved, nil
+}
+
+func (s *service) enqueueJob(ctx context.Context, runID uuid.UUID) error {
+	payload, _ := json.Marshal(buildPayload{RunID: runID})
+	if _, err := s.jobs.Enqueue(ctx, JobTypeBuild, payload, time.Now(), 3); err != nil {
+		return errs.Wrap(err, errs.CodeInternal, "enqueue codeindex.build")
+	}
+	return nil
+}
+
+func (s *service) Search(ctx context.Context, wsID uuid.UUID, q SearchQuery) ([]Snippet, error) {
+	emb, _, model, _, err := s.embedSel.Embedder(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if q.Text == "" {
+		return nil, errs.New(errs.CodeInvalidInput, "query text required")
+	}
+	topK := q.TopK
+	if topK <= 0 {
+		topK = 10
+	}
+	if topK > s.maxTopK {
+		topK = s.maxTopK
+	}
+	// Ensure there is a completed run before paying for an embedding call.
+	latest, err := s.repo.GetLatestCompletedRun(ctx, wsID)
+	if err != nil {
+		return nil, err
+	}
+	if latest == nil {
+		return nil, errs.New(errs.CodeNotFound, "no completed code index for workspace; reindex first")
+	}
+	vecs, err := emb.Embed(ctx, model, []string{q.Text})
+	if err != nil {
+		return nil, errs.Wrap(err, errs.CodeInternal, "embed query")
+	}
+	if len(vecs) != 1 {
+		return nil, errs.New(errs.CodeInternal, "embed query: unexpected vector count")
+	}
+	return s.repo.SearchKNN(ctx, wsID, vecs[0], topK, q.PathPrefix, q.Lang)
+}
+
+func (s *service) MarkStale(ctx context.Context, wsID uuid.UUID) error {
+	return s.repo.MarkStale(ctx, wsID)
+}

internal/codeindex/service_test.go

@@ -0,0 +1,68 @@
+package codeindex
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/require"
+
+	"github.com/yan1h/agent-coding-workflow/internal/infra/git"
+	"github.com/yan1h/agent-coding-workflow/internal/infra/llm"
+	"github.com/yan1h/agent-coding-workflow/internal/jobs"
+)
+
+type fakeEnqueuer struct{ count int }
+
+func (f *fakeEnqueuer) Enqueue(_ context.Context, typ jobs.JobType, _ json.RawMessage, _ time.Time, _ int32) (*jobs.Job, error) {
+	f.count++
+	return &jobs.Job{ID: uuid.New(), Type: typ}, nil
+}
+
+func TestService_EnqueueBuild_DisabledEmbedder(t *testing.T) {
+	repo := newFakeRepo()
+	enq := &fakeEnqueuer{}
+	svc := NewService(repo, fakeLocator{}, nil, fakeEmbedSel{err: ErrEmbeddingDisabled}, enq, 50)
+	_, err := svc.EnqueueBuild(context.Background(), uuid.New(), nil, "abc123")
+	require.ErrorIs(t, err, ErrEmbeddingDisabled)
+	require.Equal(t, 0, enq.count)
+}
+
+func TestService_EnqueueBuild_CreatesRunAndEnqueuesOnce(t *testing.T) {
+	dir, sha := tempGitRepo(t)
+	wsID := uuid.New()
+	repo := newFakeRepo()
+	enq := &fakeEnqueuer{}
+	gitr := git.NewDefaultRunner(git.DefaultConfig())
+	svc := NewService(repo, fakeLocator{dir: dir, wsID: wsID}, gitr,
+		fakeEmbedSel{emb: llm.NewFakeEmbedder()}, enq, 50)
+
+	run, err := svc.EnqueueBuild(context.Background(), wsID, nil, sha)
+	require.NoError(t, err)
+	require.Equal(t, sha, run.CommitSHA)
+	require.Equal(t, 1, enq.count)
+	require.Len(t, repo.runs, 1)
+
+	// Re-enqueue at the same commit while pending → no new job, no new run.
+	run2, err := svc.EnqueueBuild(context.Background(), wsID, nil, sha)
+	require.NoError(t, err)
+	require.Equal(t, run.ID, run2.ID)
+	require.Equal(t, 1, enq.count, "idempotent: pending run is reused")
+	require.Len(t, repo.runs, 1)
+}
+
+func TestService_Search_NoCompletedRun(t *testing.T) {
+	repo := newFakeRepo()
+	svc := NewService(repo, fakeLocator{}, nil, fakeEmbedSel{emb: llm.NewFakeEmbedder()}, &fakeEnqueuer{}, 50)
+	_, err := svc.Search(context.Background(), uuid.New(), SearchQuery{Text: "foo"})
+	require.Error(t, err) // no completed index yet
+}
+
+func TestService_Search_EmptyQuery(t *testing.T) {
+	repo := newFakeRepo()
+	svc := NewService(repo, fakeLocator{}, nil, fakeEmbedSel{emb: llm.NewFakeEmbedder()}, &fakeEnqueuer{}, 50)
+	_, err := svc.Search(context.Background(), uuid.New(), SearchQuery{Text: ""})
+	require.Error(t, err)
+}

internal/codeindex/sqlc/chunks.sql.go

@@ -0,0 +1,36 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: chunks.sql
+
+package codeindexsqlc
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgtype"
+)
+
+const countChunksByRun = `-- name: CountChunksByRun :one
+SELECT count(*) FROM code_chunks WHERE run_id = $1
+`
+
+func (q *Queries) CountChunksByRun(ctx context.Context, runID pgtype.UUID) (int64, error) {
+	row := q.db.QueryRow(ctx, countChunksByRun, runID)
+	var count int64
+	err := row.Scan(&count)
+	return count, err
+}
+
+const deleteChunksByRun = `-- name: DeleteChunksByRun :exec
+
+DELETE FROM code_chunks WHERE run_id = $1
+`
+
+// The embedding (vector) column is intentionally excluded from every sqlc query
+// here: sqlc has no native pgvector type. Vector INSERT (bulk) and cosine-KNN
+// SELECT are hand-written in repository.go using the pgvector text literal format.
+func (q *Queries) DeleteChunksByRun(ctx context.Context, runID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteChunksByRun, runID)
+	return err
+}

internal/codeindex/sqlc/db.go

@@ -0,0 +1,32 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+
+package codeindexsqlc
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+)
+
+type DBTX interface {
+	Exec(context.Context, string, ...interface{}) (pgconn.CommandTag, error)
+	Query(context.Context, string, ...interface{}) (pgx.Rows, error)
+	QueryRow(context.Context, string, ...interface{}) pgx.Row
+}
+
+func New(db DBTX) *Queries {
+	return &Queries{db: db}
+}
+
+type Queries struct {
+	db DBTX
+}
+
+func (q *Queries) WithTx(tx pgx.Tx) *Queries {
+	return &Queries{
+		db: tx,
+	}
+}

internal/codeindex/sqlc/models.go

@@ -0,0 +1,593 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+
+package codeindexsqlc
+
+import (
+	"net/netip"
+
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/pgvector/pgvector-go"
+)
+
+type AcpAgentKind struct {
+	ID                  pgtype.UUID        `json:"id"`
+	Name                string             `json:"name"`
+	DisplayName         string             `json:"display_name"`
+	Description         string             `json:"description"`
+	BinaryPath          string             `json:"binary_path"`
+	Args                []string           `json:"args"`
+	EncryptedEnv        []byte             `json:"encrypted_env"`
+	Enabled             bool               `json:"enabled"`
+	CreatedBy           pgtype.UUID        `json:"created_by"`
+	CreatedAt           pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt           pgtype.Timestamptz `json:"updated_at"`
+	ToolAllowlist       []string           `json:"tool_allowlist"`
+	ClientType          string             `json:"client_type"`
+	EncryptedMcpServers []byte             `json:"encrypted_mcp_servers"`
+	ModelID             pgtype.UUID        `json:"model_id"`
+	MaxCostUsd          pgtype.Numeric     `json:"max_cost_usd"`
+	MaxTokens           *int64             `json:"max_tokens"`
+	MaxWallClockSeconds *int32             `json:"max_wall_clock_seconds"`
+	KeyVersion          int16              `json:"key_version"`
+}
+
+type AcpAgentKindConfigFile struct {
+	ID               pgtype.UUID        `json:"id"`
+	AgentKindID      pgtype.UUID        `json:"agent_kind_id"`
+	RelPath          string             `json:"rel_path"`
+	EncryptedContent []byte             `json:"encrypted_content"`
+	UpdatedBy        pgtype.UUID        `json:"updated_by"`
+	CreatedAt        pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt        pgtype.Timestamptz `json:"updated_at"`
+	KeyVersion       int16              `json:"key_version"`
+}
+
+type AcpEvent struct {
+	ID          int64              `json:"id"`
+	SessionID   pgtype.UUID        `json:"session_id"`
+	Direction   string             `json:"direction"`
+	RpcKind     string             `json:"rpc_kind"`
+	Method      *string            `json:"method"`
+	Payload     []byte             `json:"payload"`
+	PayloadSize int32              `json:"payload_size"`
+	Truncated   bool               `json:"truncated"`
+	CreatedAt   pgtype.Timestamptz `json:"created_at"`
+}
+
+type AcpPermissionRequest struct {
+	ID             pgtype.UUID        `json:"id"`
+	SessionID      pgtype.UUID        `json:"session_id"`
+	AgentRequestID string             `json:"agent_request_id"`
+	ToolName       string             `json:"tool_name"`
+	ToolCall       []byte             `json:"tool_call"`
+	Options        []byte             `json:"options"`
+	Status         string             `json:"status"`
+	ChosenOptionID *string            `json:"chosen_option_id"`
+	DecidedBy      pgtype.UUID        `json:"decided_by"`
+	DecidedAt      pgtype.Timestamptz `json:"decided_at"`
+	CreatedAt      pgtype.Timestamptz `json:"created_at"`
+}
+
+type AcpSession struct {
+	ID                        pgtype.UUID        `json:"id"`
+	WorkspaceID               pgtype.UUID        `json:"workspace_id"`
+	ProjectID                 pgtype.UUID        `json:"project_id"`
+	AgentKindID               pgtype.UUID        `json:"agent_kind_id"`
+	UserID                    pgtype.UUID        `json:"user_id"`
+	IssueID                   pgtype.UUID        `json:"issue_id"`
+	RequirementID             pgtype.UUID        `json:"requirement_id"`
+	AgentSessionID            *string            `json:"agent_session_id"`
+	Branch                    string             `json:"branch"`
+	CwdPath                   string             `json:"cwd_path"`
+	IsMainWorktree            bool               `json:"is_main_worktree"`
+	Status                    string             `json:"status"`
+	Pid                       *int32             `json:"pid"`
+	ExitCode                  *int32             `json:"exit_code"`
+	LastError                 *string            `json:"last_error"`
+	StartedAt                 pgtype.Timestamptz `json:"started_at"`
+	EndedAt                   pgtype.Timestamptz `json:"ended_at"`
+	LastStopReason            *string            `json:"last_stop_reason"`
+	OrchestratorStepID        pgtype.UUID        `json:"orchestrator_step_id"`
+	PromptTokens              int64              `json:"prompt_tokens"`
+	CompletionTokens          int64              `json:"completion_tokens"`
+	ThinkingTokens            int64              `json:"thinking_tokens"`
+	TotalCostUsd              pgtype.Numeric     `json:"total_cost_usd"`
+	LastActivityAt            pgtype.Timestamptz `json:"last_activity_at"`
+	BudgetMaxCostUsd          pgtype.Numeric     `json:"budget_max_cost_usd"`
+	BudgetMaxTokens           *int64             `json:"budget_max_tokens"`
+	BudgetMaxWallClockSeconds *int32             `json:"budget_max_wall_clock_seconds"`
+	TerminatedReason          *string            `json:"terminated_reason"`
+	SandboxMode               *string            `json:"sandbox_mode"`
+	CostUsd                   pgtype.Numeric     `json:"cost_usd"`
+	TokensTotal               int64              `json:"tokens_total"`
+}
+
+type AcpSessionUsage struct {
+	ID               int64              `json:"id"`
+	SessionID        pgtype.UUID        `json:"session_id"`
+	UserID           pgtype.UUID        `json:"user_id"`
+	ProjectID        pgtype.UUID        `json:"project_id"`
+	AgentKindID      pgtype.UUID        `json:"agent_kind_id"`
+	ModelID          pgtype.UUID        `json:"model_id"`
+	PromptTokens     int64              `json:"prompt_tokens"`
+	CompletionTokens int64              `json:"completion_tokens"`
+	ThinkingTokens   int64              `json:"thinking_tokens"`
+	CostUsd          pgtype.Numeric     `json:"cost_usd"`
+	SourceEventID    *int64             `json:"source_event_id"`
+	CreatedAt        pgtype.Timestamptz `json:"created_at"`
+}
+
+type AcpTurn struct {
+	ID              int64              `json:"id"`
+	SessionID       pgtype.UUID        `json:"session_id"`
+	TurnIndex       int32              `json:"turn_index"`
+	PromptRequestID *string            `json:"prompt_request_id"`
+	Status          string             `json:"status"`
+	StopReason      *string            `json:"stop_reason"`
+	UpdateCount     int32              `json:"update_count"`
+	StartedAt       pgtype.Timestamptz `json:"started_at"`
+	CompletedAt     pgtype.Timestamptz `json:"completed_at"`
+}
+
+type AuditLog struct {
+	ID         int64              `json:"id"`
+	UserID     pgtype.UUID        `json:"user_id"`
+	Action     string             `json:"action"`
+	TargetType *string            `json:"target_type"`
+	TargetID   *string            `json:"target_id"`
+	Ip         *netip.Addr        `json:"ip"`
+	Metadata   []byte             `json:"metadata"`
+	CreatedAt  pgtype.Timestamptz `json:"created_at"`
+}
+
+type ChangeRequest struct {
+	ID             pgtype.UUID        `json:"id"`
+	ProjectID      pgtype.UUID        `json:"project_id"`
+	WorkspaceID    pgtype.UUID        `json:"workspace_id"`
+	RequirementID  pgtype.UUID        `json:"requirement_id"`
+	IssueID        pgtype.UUID        `json:"issue_id"`
+	Number         int32              `json:"number"`
+	Title          string             `json:"title"`
+	Description    string             `json:"description"`
+	SourceBranch   string             `json:"source_branch"`
+	TargetBranch   string             `json:"target_branch"`
+	State          string             `json:"state"`
+	ReviewVerdict  string             `json:"review_verdict"`
+	CiState        string             `json:"ci_state"`
+	Provider       string             `json:"provider"`
+	ExternalID     *int64             `json:"external_id"`
+	ExternalUrl    string             `json:"external_url"`
+	MergeCommitSha string             `json:"merge_commit_sha"`
+	ReviewedBy     pgtype.UUID        `json:"reviewed_by"`
+	ReviewedAt     pgtype.Timestamptz `json:"reviewed_at"`
+	CreatedBy      pgtype.UUID        `json:"created_by"`
+	MergedAt       pgtype.Timestamptz `json:"merged_at"`
+	CreatedAt      pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt      pgtype.Timestamptz `json:"updated_at"`
+}
+
+type CodeChunk struct {
+	ID          pgtype.UUID        `json:"id"`
+	RunID       pgtype.UUID        `json:"run_id"`
+	WorkspaceID pgtype.UUID        `json:"workspace_id"`
+	CommitSha   string             `json:"commit_sha"`
+	FilePath    string             `json:"file_path"`
+	Lang        *string            `json:"lang"`
+	StartLine   int32              `json:"start_line"`
+	EndLine     int32              `json:"end_line"`
+	Content     string             `json:"content"`
+	ContentSha  []byte             `json:"content_sha"`
+	TokenCount  *int32             `json:"token_count"`
+	Embedding   *pgvector.Vector   `json:"embedding"`
+	CreatedAt   pgtype.Timestamptz `json:"created_at"`
+}
+
+type CodeIndexRun struct {
+	ID                  pgtype.UUID        `json:"id"`
+	WorkspaceID         pgtype.UUID        `json:"workspace_id"`
+	WorktreeID          pgtype.UUID        `json:"worktree_id"`
+	Branch              string             `json:"branch"`
+	CommitSha           string             `json:"commit_sha"`
+	Status              string             `json:"status"`
+	EmbeddingEndpointID pgtype.UUID        `json:"embedding_endpoint_id"`
+	EmbeddingModel      string             `json:"embedding_model"`
+	Dims                int32              `json:"dims"`
+	FilesIndexed        int32              `json:"files_indexed"`
+	ChunksIndexed       int32              `json:"chunks_indexed"`
+	Error               *string            `json:"error"`
+	StartedAt           pgtype.Timestamptz `json:"started_at"`
+	FinishedAt          pgtype.Timestamptz `json:"finished_at"`
+	CreatedAt           pgtype.Timestamptz `json:"created_at"`
+}
+
+type CommitSummary struct {
+	ID          pgtype.UUID        `json:"id"`
+	WorkspaceID pgtype.UUID        `json:"workspace_id"`
+	WorktreeID  pgtype.UUID        `json:"worktree_id"`
+	Branch      string             `json:"branch"`
+	CommitSha   string             `json:"commit_sha"`
+	Kind        string             `json:"kind"`
+	Title       *string            `json:"title"`
+	BodyMd      string             `json:"body_md"`
+	Model       *string            `json:"model"`
+	Status      string             `json:"status"`
+	Error       *string            `json:"error"`
+	CreatedAt   pgtype.Timestamptz `json:"created_at"`
+}
+
+type Conversation struct {
+	ID               pgtype.UUID        `json:"id"`
+	UserID           pgtype.UUID        `json:"user_id"`
+	ProjectID        pgtype.UUID        `json:"project_id"`
+	WorkspaceID      pgtype.UUID        `json:"workspace_id"`
+	IssueID          pgtype.UUID        `json:"issue_id"`
+	ModelID          pgtype.UUID        `json:"model_id"`
+	SystemPrompt     string             `json:"system_prompt"`
+	Title            *string            `json:"title"`
+	TitleGeneratedAt pgtype.Timestamptz `json:"title_generated_at"`
+	CreatedAt        pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt        pgtype.Timestamptz `json:"updated_at"`
+	DeletedAt        pgtype.Timestamptz `json:"deleted_at"`
+	RequirementID    pgtype.UUID        `json:"requirement_id"`
+}
+
+type CryptoKey struct {
+	Version   int32              `json:"version"`
+	Provider  string             `json:"provider"`
+	KeyRef    *string            `json:"key_ref"`
+	Status    string             `json:"status"`
+	CreatedAt pgtype.Timestamptz `json:"created_at"`
+}
+
+type GitCredential struct {
+	ID              pgtype.UUID        `json:"id"`
+	WorkspaceID     pgtype.UUID        `json:"workspace_id"`
+	Kind            string             `json:"kind"`
+	Username        *string            `json:"username"`
+	EncryptedSecret []byte             `json:"encrypted_secret"`
+	Fingerprint     *string            `json:"fingerprint"`
+	CreatedAt       pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt       pgtype.Timestamptz `json:"updated_at"`
+	KeyVersion      int16              `json:"key_version"`
+}
+
+type Issue struct {
+	ID            pgtype.UUID        `json:"id"`
+	ProjectID     pgtype.UUID        `json:"project_id"`
+	RequirementID pgtype.UUID        `json:"requirement_id"`
+	Number        int32              `json:"number"`
+	Title         string             `json:"title"`
+	Description   string             `json:"description"`
+	Status        string             `json:"status"`
+	AssigneeID    pgtype.UUID        `json:"assignee_id"`
+	CreatedBy     pgtype.UUID        `json:"created_by"`
+	ClosedAt      pgtype.Timestamptz `json:"closed_at"`
+	CreatedAt     pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt     pgtype.Timestamptz `json:"updated_at"`
+	WorkspaceID   pgtype.UUID        `json:"workspace_id"`
+	ParentID      pgtype.UUID        `json:"parent_id"`
+	Priority      int32              `json:"priority"`
+}
+
+type IssueDependency struct {
+	ID        pgtype.UUID        `json:"id"`
+	ProjectID pgtype.UUID        `json:"project_id"`
+	BlockedID pgtype.UUID        `json:"blocked_id"`
+	BlockerID pgtype.UUID        `json:"blocker_id"`
+	CreatedBy pgtype.UUID        `json:"created_by"`
+	CreatedAt pgtype.Timestamptz `json:"created_at"`
+}
+
+type Job struct {
+	ID          pgtype.UUID        `json:"id"`
+	Type        string             `json:"type"`
+	Payload     []byte             `json:"payload"`
+	Status      string             `json:"status"`
+	ScheduledAt pgtype.Timestamptz `json:"scheduled_at"`
+	Attempts    int32              `json:"attempts"`
+	MaxAttempts int32              `json:"max_attempts"`
+	LeasedAt    pgtype.Timestamptz `json:"leased_at"`
+	LeasedBy    *string            `json:"leased_by"`
+	LastError   *string            `json:"last_error"`
+	CompletedAt pgtype.Timestamptz `json:"completed_at"`
+	CreatedAt   pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt   pgtype.Timestamptz `json:"updated_at"`
+}
+
+type LlmEndpoint struct {
+	ID              pgtype.UUID        `json:"id"`
+	Provider        string             `json:"provider"`
+	DisplayName     string             `json:"display_name"`
+	BaseUrl         string             `json:"base_url"`
+	ApiKeyEncrypted []byte             `json:"api_key_encrypted"`
+	CreatedBy       pgtype.UUID        `json:"created_by"`
+	CreatedAt       pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt       pgtype.Timestamptz `json:"updated_at"`
+	KeyVersion      int16              `json:"key_version"`
+}
+
+type LlmModel struct {
+	ID                           pgtype.UUID        `json:"id"`
+	EndpointID                   pgtype.UUID        `json:"endpoint_id"`
+	ModelID                      string             `json:"model_id"`
+	DisplayName                  string             `json:"display_name"`
+	Capabilities                 []byte             `json:"capabilities"`
+	ContextWindow                int32              `json:"context_window"`
+	MaxOutputTokens              int32              `json:"max_output_tokens"`
+	PromptPricePerMillionUsd     pgtype.Numeric     `json:"prompt_price_per_million_usd"`
+	CompletionPricePerMillionUsd pgtype.Numeric     `json:"completion_price_per_million_usd"`
+	ThinkingPricePerMillionUsd   pgtype.Numeric     `json:"thinking_price_per_million_usd"`
+	IsTitleGenerator             bool               `json:"is_title_generator"`
+	Enabled                      bool               `json:"enabled"`
+	SortOrder                    int32              `json:"sort_order"`
+	CreatedAt                    pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt                    pgtype.Timestamptz `json:"updated_at"`
+}
+
+type LlmUsage struct {
+	ID               int64              `json:"id"`
+	ConversationID   pgtype.UUID        `json:"conversation_id"`
+	MessageID        int64              `json:"message_id"`
+	UserID           pgtype.UUID        `json:"user_id"`
+	EndpointID       pgtype.UUID        `json:"endpoint_id"`
+	ModelID          pgtype.UUID        `json:"model_id"`
+	PromptTokens     int32              `json:"prompt_tokens"`
+	CompletionTokens int32              `json:"completion_tokens"`
+	ThinkingTokens   int32              `json:"thinking_tokens"`
+	CostUsd          pgtype.Numeric     `json:"cost_usd"`
+	CreatedAt        pgtype.Timestamptz `json:"created_at"`
+}
+
+type McpToken struct {
+	ID           pgtype.UUID        `json:"id"`
+	TokenHash    []byte             `json:"token_hash"`
+	UserID       pgtype.UUID        `json:"user_id"`
+	Name         string             `json:"name"`
+	Issuer       string             `json:"issuer"`
+	Scope        []byte             `json:"scope"`
+	AcpSessionID pgtype.UUID        `json:"acp_session_id"`
+	ExpiresAt    pgtype.Timestamptz `json:"expires_at"`
+	LastUsedAt   pgtype.Timestamptz `json:"last_used_at"`
+	RevokedAt    pgtype.Timestamptz `json:"revoked_at"`
+	CreatedBy    pgtype.UUID        `json:"created_by"`
+	CreatedAt    pgtype.Timestamptz `json:"created_at"`
+}
+
+type Message struct {
+	ID               int64              `json:"id"`
+	ConversationID   pgtype.UUID        `json:"conversation_id"`
+	Role             string             `json:"role"`
+	Content          string             `json:"content"`
+	Thinking         *string            `json:"thinking"`
+	ToolCalls        []byte             `json:"tool_calls"`
+	Status           string             `json:"status"`
+	ErrorMessage     *string            `json:"error_message"`
+	PromptTokens     *int32             `json:"prompt_tokens"`
+	CompletionTokens *int32             `json:"completion_tokens"`
+	ThinkingTokens   *int32             `json:"thinking_tokens"`
+	CreatedAt        pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt        pgtype.Timestamptz `json:"updated_at"`
+}
+
+type MessageAttachment struct {
+	ID          pgtype.UUID        `json:"id"`
+	UserID      pgtype.UUID        `json:"user_id"`
+	MessageID   *int64             `json:"message_id"`
+	Filename    string             `json:"filename"`
+	MimeType    string             `json:"mime_type"`
+	SizeBytes   int64              `json:"size_bytes"`
+	Sha256      string             `json:"sha256"`
+	StoragePath string             `json:"storage_path"`
+	CreatedAt   pgtype.Timestamptz `json:"created_at"`
+}
+
+type Notification struct {
+	ID        pgtype.UUID        `json:"id"`
+	UserID    pgtype.UUID        `json:"user_id"`
+	Topic     string             `json:"topic"`
+	Severity  string             `json:"severity"`
+	Title     string             `json:"title"`
+	Body      string             `json:"body"`
+	Link      *string            `json:"link"`
+	Metadata  []byte             `json:"metadata"`
+	ReadAt    pgtype.Timestamptz `json:"read_at"`
+	CreatedAt pgtype.Timestamptz `json:"created_at"`
+}
+
+type NotificationPref struct {
+	UserID          pgtype.UUID        `json:"user_id"`
+	EmailEnabled    bool               `json:"email_enabled"`
+	ImEnabled       bool               `json:"im_enabled"`
+	ImWebhookUrlEnc []byte             `json:"im_webhook_url_enc"`
+	MinSeverity     string             `json:"min_severity"`
+	UpdatedAt       pgtype.Timestamptz `json:"updated_at"`
+}
+
+type OrchestratorRun struct {
+	ID            pgtype.UUID        `json:"id"`
+	ProjectID     pgtype.UUID        `json:"project_id"`
+	RequirementID pgtype.UUID        `json:"requirement_id"`
+	WorkspaceID   pgtype.UUID        `json:"workspace_id"`
+	OwnerID       pgtype.UUID        `json:"owner_id"`
+	Status        string             `json:"status"`
+	CurrentPhase  string             `json:"current_phase"`
+	Config        []byte             `json:"config"`
+	LastError     *string            `json:"last_error"`
+	CreatedAt     pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt     pgtype.Timestamptz `json:"updated_at"`
+	EndedAt       pgtype.Timestamptz `json:"ended_at"`
+}
+
+type OrchestratorStep struct {
+	ID           pgtype.UUID        `json:"id"`
+	RunID        pgtype.UUID        `json:"run_id"`
+	Phase        string             `json:"phase"`
+	Attempt      int32              `json:"attempt"`
+	ParentStepID pgtype.UUID        `json:"parent_step_id"`
+	Depth        int32              `json:"depth"`
+	Status       string             `json:"status"`
+	AgentKindID  pgtype.UUID        `json:"agent_kind_id"`
+	AcpSessionID pgtype.UUID        `json:"acp_session_id"`
+	Prompt       string             `json:"prompt"`
+	StopReason   *string            `json:"stop_reason"`
+	GateResult   []byte             `json:"gate_result"`
+	LastError    *string            `json:"last_error"`
+	JobID        pgtype.UUID        `json:"job_id"`
+	CreatedAt    pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt    pgtype.Timestamptz `json:"updated_at"`
+	EndedAt      pgtype.Timestamptz `json:"ended_at"`
+}
+
+type Project struct {
+	ID          pgtype.UUID        `json:"id"`
+	Slug        string             `json:"slug"`
+	Name        string             `json:"name"`
+	Description string             `json:"description"`
+	Visibility  string             `json:"visibility"`
+	OwnerID     pgtype.UUID        `json:"owner_id"`
+	ArchivedAt  pgtype.Timestamptz `json:"archived_at"`
+	CreatedAt   pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt   pgtype.Timestamptz `json:"updated_at"`
+}
+
+type ProjectMember struct {
+	ProjectID pgtype.UUID        `json:"project_id"`
+	UserID    pgtype.UUID        `json:"user_id"`
+	Role      string             `json:"role"`
+	CreatedAt pgtype.Timestamptz `json:"created_at"`
+	AddedBy   pgtype.UUID        `json:"added_by"`
+}
+
+type ProjectMemory struct {
+	ID             pgtype.UUID        `json:"id"`
+	ProjectID      pgtype.UUID        `json:"project_id"`
+	WorkspaceID    pgtype.UUID        `json:"workspace_id"`
+	Kind           string             `json:"kind"`
+	Title          string             `json:"title"`
+	Body           string             `json:"body"`
+	Tags           []string           `json:"tags"`
+	Source         string             `json:"source"`
+	Embedding      *pgvector.Vector   `json:"embedding"`
+	EmbeddingModel *string            `json:"embedding_model"`
+	CreatedBy      pgtype.UUID        `json:"created_by"`
+	CreatedAt      pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt      pgtype.Timestamptz `json:"updated_at"`
+}
+
+type PromptTemplate struct {
+	ID        pgtype.UUID        `json:"id"`
+	Name      string             `json:"name"`
+	Content   string             `json:"content"`
+	Scope     string             `json:"scope"`
+	OwnerID   pgtype.UUID        `json:"owner_id"`
+	CreatedAt pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt pgtype.Timestamptz `json:"updated_at"`
+}
+
+type Requirement struct {
+	ID          pgtype.UUID        `json:"id"`
+	ProjectID   pgtype.UUID        `json:"project_id"`
+	Number      int32              `json:"number"`
+	Title       string             `json:"title"`
+	Description string             `json:"description"`
+	Phase       string             `json:"phase"`
+	Status      string             `json:"status"`
+	OwnerID     pgtype.UUID        `json:"owner_id"`
+	ClosedAt    pgtype.Timestamptz `json:"closed_at"`
+	CreatedAt   pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt   pgtype.Timestamptz `json:"updated_at"`
+	WorkspaceID pgtype.UUID        `json:"workspace_id"`
+}
+
+type RequirementArtifact struct {
+	ID              pgtype.UUID        `json:"id"`
+	RequirementID   pgtype.UUID        `json:"requirement_id"`
+	Phase           string             `json:"phase"`
+	Version         int32              `json:"version"`
+	Content         string             `json:"content"`
+	Note            string             `json:"note"`
+	SourceMessageID *int64             `json:"source_message_id"`
+	CreatedBy       pgtype.UUID        `json:"created_by"`
+	CreatedAt       pgtype.Timestamptz `json:"created_at"`
+	Verdict         string             `json:"verdict"`
+}
+
+type RequirementPhasePointer struct {
+	RequirementID      pgtype.UUID        `json:"requirement_id"`
+	Phase              string             `json:"phase"`
+	ApprovedArtifactID pgtype.UUID        `json:"approved_artifact_id"`
+	ApprovedBy         pgtype.UUID        `json:"approved_by"`
+	ApprovedAt         pgtype.Timestamptz `json:"approved_at"`
+	UpdatedAt          pgtype.Timestamptz `json:"updated_at"`
+}
+
+type User struct {
+	ID           pgtype.UUID        `json:"id"`
+	Email        string             `json:"email"`
+	PasswordHash string             `json:"password_hash"`
+	DisplayName  string             `json:"display_name"`
+	IsAdmin      bool               `json:"is_admin"`
+	CreatedAt    pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt    pgtype.Timestamptz `json:"updated_at"`
+	Enabled      bool               `json:"enabled"`
+}
+
+type UserSession struct {
+	ID         pgtype.UUID        `json:"id"`
+	UserID     pgtype.UUID        `json:"user_id"`
+	TokenHash  []byte             `json:"token_hash"`
+	ExpiresAt  pgtype.Timestamptz `json:"expires_at"`
+	LastSeenAt pgtype.Timestamptz `json:"last_seen_at"`
+	CreatedAt  pgtype.Timestamptz `json:"created_at"`
+}
+
+type Workspace struct {
+	ID                  pgtype.UUID        `json:"id"`
+	ProjectID           pgtype.UUID        `json:"project_id"`
+	Slug                string             `json:"slug"`
+	Name                string             `json:"name"`
+	Description         string             `json:"description"`
+	GitRemoteUrl        string             `json:"git_remote_url"`
+	DefaultBranch       string             `json:"default_branch"`
+	MainPath            string             `json:"main_path"`
+	SyncStatus          string             `json:"sync_status"`
+	LastSyncedAt        pgtype.Timestamptz `json:"last_synced_at"`
+	LastSyncError       *string            `json:"last_sync_error"`
+	CreatedAt           pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt           pgtype.Timestamptz `json:"updated_at"`
+	ActiveMainSessionID pgtype.UUID        `json:"active_main_session_id"`
+}
+
+type WorkspaceRunProfile struct {
+	ID            pgtype.UUID        `json:"id"`
+	WorkspaceID   pgtype.UUID        `json:"workspace_id"`
+	Slug          string             `json:"slug"`
+	Name          string             `json:"name"`
+	Description   string             `json:"description"`
+	Command       string             `json:"command"`
+	Args          []string           `json:"args"`
+	EncryptedEnv  []byte             `json:"encrypted_env"`
+	Enabled       bool               `json:"enabled"`
+	LastStartedAt pgtype.Timestamptz `json:"last_started_at"`
+	LastExitCode  *int32             `json:"last_exit_code"`
+	LastError     string             `json:"last_error"`
+	CreatedBy     pgtype.UUID        `json:"created_by"`
+	CreatedAt     pgtype.Timestamptz `json:"created_at"`
+	UpdatedAt     pgtype.Timestamptz `json:"updated_at"`
+	KeyVersion    int16              `json:"key_version"`
+}
+
+type WorkspaceWorktree struct {
+	ID             pgtype.UUID        `json:"id"`
+	WorkspaceID    pgtype.UUID        `json:"workspace_id"`
+	Branch         string             `json:"branch"`
+	Path           string             `json:"path"`
+	Status         string             `json:"status"`
+	ActiveHolder   *string            `json:"active_holder"`
+	AcquiredAt     pgtype.Timestamptz `json:"acquired_at"`
+	LastUsedAt     pgtype.Timestamptz `json:"last_used_at"`
+	CreatedAt      pgtype.Timestamptz `json:"created_at"`
+	PruneWarningAt pgtype.Timestamptz `json:"prune_warning_at"`
+}

internal/codeindex/sqlc/runs.sql.go

@@ -0,0 +1,251 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: runs.sql
+
+package codeindexsqlc
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgtype"
+)
+
+const getLatestCompletedRun = `-- name: GetLatestCompletedRun :one
+SELECT id, workspace_id, worktree_id, branch, commit_sha, status,
+       embedding_endpoint_id, embedding_model, dims,
+       files_indexed, chunks_indexed, error, started_at, finished_at, created_at
+FROM code_index_runs
+WHERE workspace_id = $1 AND status = 'completed'
+ORDER BY created_at DESC
+LIMIT 1
+`
+
+func (q *Queries) GetLatestCompletedRun(ctx context.Context, workspaceID pgtype.UUID) (CodeIndexRun, error) {
+	row := q.db.QueryRow(ctx, getLatestCompletedRun, workspaceID)
+	var i CodeIndexRun
+	err := row.Scan(
+		&i.ID,
+		&i.WorkspaceID,
+		&i.WorktreeID,
+		&i.Branch,
+		&i.CommitSha,
+		&i.Status,
+		&i.EmbeddingEndpointID,
+		&i.EmbeddingModel,
+		&i.Dims,
+		&i.FilesIndexed,
+		&i.ChunksIndexed,
+		&i.Error,
+		&i.StartedAt,
+		&i.FinishedAt,
+		&i.CreatedAt,
+	)
+	return i, err
+}
+
+const getRun = `-- name: GetRun :one
+SELECT id, workspace_id, worktree_id, branch, commit_sha, status,
+       embedding_endpoint_id, embedding_model, dims,
+       files_indexed, chunks_indexed, error, started_at, finished_at, created_at
+FROM code_index_runs
+WHERE id = $1
+`
+
+func (q *Queries) GetRun(ctx context.Context, id pgtype.UUID) (CodeIndexRun, error) {
+	row := q.db.QueryRow(ctx, getRun, id)
+	var i CodeIndexRun
+	err := row.Scan(
+		&i.ID,
+		&i.WorkspaceID,
+		&i.WorktreeID,
+		&i.Branch,
+		&i.CommitSha,
+		&i.Status,
+		&i.EmbeddingEndpointID,
+		&i.EmbeddingModel,
+		&i.Dims,
+		&i.FilesIndexed,
+		&i.ChunksIndexed,
+		&i.Error,
+		&i.StartedAt,
+		&i.FinishedAt,
+		&i.CreatedAt,
+	)
+	return i, err
+}
+
+const getRunByCommit = `-- name: GetRunByCommit :one
+SELECT id, workspace_id, worktree_id, branch, commit_sha, status,
+       embedding_endpoint_id, embedding_model, dims,
+       files_indexed, chunks_indexed, error, started_at, finished_at, created_at
+FROM code_index_runs
+WHERE workspace_id = $1 AND commit_sha = $2 AND embedding_model = $3
+`
+
+type GetRunByCommitParams struct {
+	WorkspaceID    pgtype.UUID `json:"workspace_id"`
+	CommitSha      string      `json:"commit_sha"`
+	EmbeddingModel string      `json:"embedding_model"`
+}
+
+func (q *Queries) GetRunByCommit(ctx context.Context, arg GetRunByCommitParams) (CodeIndexRun, error) {
+	row := q.db.QueryRow(ctx, getRunByCommit, arg.WorkspaceID, arg.CommitSha, arg.EmbeddingModel)
+	var i CodeIndexRun
+	err := row.Scan(
+		&i.ID,
+		&i.WorkspaceID,
+		&i.WorktreeID,
+		&i.Branch,
+		&i.CommitSha,
+		&i.Status,
+		&i.EmbeddingEndpointID,
+		&i.EmbeddingModel,
+		&i.Dims,
+		&i.FilesIndexed,
+		&i.ChunksIndexed,
+		&i.Error,
+		&i.StartedAt,
+		&i.FinishedAt,
+		&i.CreatedAt,
+	)
+	return i, err
+}
+
+const insertRun = `-- name: InsertRun :one
+INSERT INTO code_index_runs (
+  id, workspace_id, worktree_id, branch, commit_sha, status,
+  embedding_endpoint_id, embedding_model, dims
+) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+RETURNING id, workspace_id, worktree_id, branch, commit_sha, status,
+          embedding_endpoint_id, embedding_model, dims,
+          files_indexed, chunks_indexed, error, started_at, finished_at, created_at
+`
+
+type InsertRunParams struct {
+	ID                  pgtype.UUID `json:"id"`
+	WorkspaceID         pgtype.UUID `json:"workspace_id"`
+	WorktreeID          pgtype.UUID `json:"worktree_id"`
+	Branch              string      `json:"branch"`
+	CommitSha           string      `json:"commit_sha"`
+	Status              string      `json:"status"`
+	EmbeddingEndpointID pgtype.UUID `json:"embedding_endpoint_id"`
+	EmbeddingModel      string      `json:"embedding_model"`
+	Dims                int32       `json:"dims"`
+}
+
+func (q *Queries) InsertRun(ctx context.Context, arg InsertRunParams) (CodeIndexRun, error) {
+	row := q.db.QueryRow(ctx, insertRun,
+		arg.ID,
+		arg.WorkspaceID,
+		arg.WorktreeID,
+		arg.Branch,
+		arg.CommitSha,
+		arg.Status,
+		arg.EmbeddingEndpointID,
+		arg.EmbeddingModel,
+		arg.Dims,
+	)
+	var i CodeIndexRun
+	err := row.Scan(
+		&i.ID,
+		&i.WorkspaceID,
+		&i.WorktreeID,
+		&i.Branch,
+		&i.CommitSha,
+		&i.Status,
+		&i.EmbeddingEndpointID,
+		&i.EmbeddingModel,
+		&i.Dims,
+		&i.FilesIndexed,
+		&i.ChunksIndexed,
+		&i.Error,
+		&i.StartedAt,
+		&i.FinishedAt,
+		&i.CreatedAt,
+	)
+	return i, err
+}
+
+const markRunCompleted = `-- name: MarkRunCompleted :exec
+UPDATE code_index_runs
+SET status = 'completed', files_indexed = $2, chunks_indexed = $3,
+    error = NULL, finished_at = now()
+WHERE id = $1
+`
+
+type MarkRunCompletedParams struct {
+	ID            pgtype.UUID `json:"id"`
+	FilesIndexed  int32       `json:"files_indexed"`
+	ChunksIndexed int32       `json:"chunks_indexed"`
+}
+
+func (q *Queries) MarkRunCompleted(ctx context.Context, arg MarkRunCompletedParams) error {
+	_, err := q.db.Exec(ctx, markRunCompleted, arg.ID, arg.FilesIndexed, arg.ChunksIndexed)
+	return err
+}
+
+const markRunFailed = `-- name: MarkRunFailed :exec
+UPDATE code_index_runs
+SET status = 'failed', error = $2, finished_at = now()
+WHERE id = $1
+`
+
+type MarkRunFailedParams struct {
+	ID    pgtype.UUID `json:"id"`
+	Error *string     `json:"error"`
+}
+
+func (q *Queries) MarkRunFailed(ctx context.Context, arg MarkRunFailedParams) error {
+	_, err := q.db.Exec(ctx, markRunFailed, arg.ID, arg.Error)
+	return err
+}
+
+const markRunRunning = `-- name: MarkRunRunning :exec
+UPDATE code_index_runs
+SET status = 'running', started_at = now()
+WHERE id = $1
+`
+
+func (q *Queries) MarkRunRunning(ctx context.Context, id pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, markRunRunning, id)
+	return err
+}
+
+const markRunsStale = `-- name: MarkRunsStale :exec
+UPDATE code_index_runs
+SET status = 'stale'
+WHERE workspace_id = $1 AND status IN ('pending','running','completed')
+`
+
+func (q *Queries) MarkRunsStale(ctx context.Context, workspaceID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, markRunsStale, workspaceID)
+	return err
+}
+
+const markStuckRunsStale = `-- name: MarkStuckRunsStale :many
+UPDATE code_index_runs
+SET status = 'stale'
+WHERE status = 'running' AND started_at < $1
+RETURNING id
+`
+
+func (q *Queries) MarkStuckRunsStale(ctx context.Context, startedAt pgtype.Timestamptz) ([]pgtype.UUID, error) {
+	rows, err := q.db.Query(ctx, markStuckRunsStale, startedAt)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []pgtype.UUID
+	for rows.Next() {
+		var id pgtype.UUID
+		if err := rows.Scan(&id); err != nil {
+			return nil, err
+		}
+		items = append(items, id)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}