From f5f07aa9aebb87ce6986442499a969e9554c14be Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 16 Oct 2026 22:56:25 -0700
Subject: [PATCH] feat(neighbors): filter by state and merge time before
 ranking

Add opt-in temporal filters before vector decoding and ranking, preserving
existing default selection and scoring. Include additive thread metadata and
a successful complete sync-and-sweep watermark, with explicit historical
coverage, reopening, and timestamp-precision limits.

Verify freshness through real sync-runner paths as well as stored run records.
Closes #238.

Co-authored-by: Masato Hoshino <g515hoshino@gmail.com>
---
 CHANGELOG.md                                  |   1 +
 docs/clustering.md                            |  27 ++
 docs/commands.md                              |   2 +-
 internal/cli/default_output_golden_test.go    | 227 +++++++++++++++
 internal/cli/help.go                          |   7 +-
 internal/cli/neighbors.go                     | 114 ++++++--
 internal/cli/neighbors_test.go                | 271 ++++++++++++++++++
 .../neighbors-closed-source.json              |  96 +++++++
 .../neighbors-include-closed.json             |  83 ++++++
 .../neighbors-limit-threshold.json            |  54 ++++
 .../testdata/default_output/neighbors.json    |  54 ++++
 .../cli/testdata/default_output/neighbors.txt |  55 ++++
 internal/store/runs.go                        |  33 +++
 internal/store/vectors.go                     |  28 ++
 internal/store/vectors_where_test.go          | 103 +++++++
 internal/syncer/closed_sweep_test.go          |  17 ++
 16 files changed, 1154 insertions(+), 18 deletions(-)
 create mode 100644 internal/cli/default_output_golden_test.go
 create mode 100644 internal/cli/neighbors_test.go
 create mode 100644 internal/cli/testdata/default_output/neighbors-closed-source.json
 create mode 100644 internal/cli/testdata/default_output/neighbors-include-closed.json
 create mode 100644 internal/cli/testdata/default_output/neighbors-limit-threshold.json
 create mode 100644 internal/cli/testdata/default_output/neighbors.json
 create mode 100644 internal/cli/testdata/default_output/neighbors.txt
 create mode 100644 internal/store/vectors_where_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c9cd4e64..c71c3b14 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Add `neighbors --open-at`, `--created-after`, and `--merged-after` to filter similar rows by time before ranking, with thread metadata and a complete-sync watermark in the output. Thanks @masatohoshino.
 - Fix large neighbor and search result lookups failing with SQLite's SQL variable limit. Thanks @masatohoshino for reporting.
 - Update the D-Bus dependency used by Linux credential storage to v5.2.4, retaining the Go 1.27.2 minimum.
 
diff --git a/docs/clustering.md b/docs/clustering.md
index 294c3eb8..a8afe12b 100644
--- a/docs/clustering.md
+++ b/docs/clustering.md
@@ -127,6 +127,33 @@ gitcrawl neighbors owner/repo --number 123 --limit 10
 | `--limit <n>` | `10` | Maximum neighbors |
 | `--threshold <float>` | `0.2` | Minimum cosine score |
 | `--include-closed` | _(off)_ | Include closed issue and pull request vectors |
+| `--open-at <time>` | _(off)_ | Only rows created by the time and not closed by then; implies `--include-closed` |
+| `--created-after <time\|ref>` | _(off)_ | Only rows created after the time, or numbered after the issue/PR reference |
+| `--merged-after <time>` | _(off)_ | Only pull requests merged after the time; implies `--include-closed` |
+
+Time filters take an RFC 3339 time or a `YYYY-MM-DD` date (UTC) and apply before `--limit`. Comparisons use SQLite date functions with millisecond precision. `--created-after` also takes an issue or pull request reference (`456`, `#456`, or its URL) and keeps rows numbered after it.
+
+Each neighbor row carries the thread's `state`, `html_url`, `is_draft`, and, when known, `author_login`, `author_association`, `created_at_gh`, `closed_at_gh`, `merged_at_gh`, and `closed_at_local`, so a closed row can be told apart from a merged one without a second lookup. The output's `state_as_of` is the start of the newest successful complete open (or all) sync, one without `--numbers`, `--limit`, or `--since`; it is omitted when none is recorded. Failed runs and partial checkpoints do not advance it. This is a sync-and-sweep watermark, not a guarantee that all historical threads have been imported.
+
+### How far row state and time filters can be trusted
+
+The archive keeps each thread's current GitHub values, not its history. What follows from that:
+
+- **Each row is current as of `state_as_of` or later.** A complete sync lists every open thread and sweeps closed threads updated since the previous complete sync started, and `state_as_of` is the start of the newest one, so it is no later than the time any row's `state`, `closed_at_gh`, and `merged_at_gh` were read: the listing runs after the start, and `sync --numbers` can refresh a row afterwards. Changes after a row was read are not in the archive. This holds once sweeps cover the time since each row was stored. The first sweep of an archive reaches back only to the earliest pull of a row that is still open (or 24 hours when there is none), so a closed row stored earlier keeps an older `closed_at_gh` if it was reopened and closed again before that; `sync --state all` refreshes every row.
+- **A merge is final.** `merged_at_gh` never changes once set. For archived rows covered by the sweeps above, `--merged-after` filters recorded merge times through `state_as_of`; later merges may be missing. Threads never imported into the archive cannot appear in results. Use `sync --state all` to backfill historical threads and refresh legacy closed rows.
+- **Creation is fixed, and numbers follow it.** `created_at_gh` and the number never change, and GitHub numbers issues and pull requests together in creation order, so `--created-after <ref>` needs no clock.
+- **`--open-at` errs only by including rows.** It reads the current `created_at` and `closed_at`, and reopening clears `closed_at`, so a row with a reopen in its history counts as open from creation to its latest close. It can list a row that was closed at that moment, but never drops one that was open, apart from the stale closed rows described above.
+
+Similarity and these filters find candidates; confirm the current state with `gh` before acting on one.
+
+```bash
+# Pull requests that were open when issue 123 was filed.
+gitcrawl neighbors owner/repo --number 123 --open-at 2026-09-01T10:00:00Z --json \
+  | jq '.neighbors[] | select(.kind == "pull_request")'
+
+# Similar pull requests merged after my pull request was opened.
+gitcrawl neighbors owner/repo --number 456 --merged-after 2026-09-15 --json
+```
 
 Useful for "what else looks like this?" without committing to a cluster. If the source row is present but lacks a current embedding, the CLI command backfills that one row when an OpenAI key is configured; otherwise it prints the exact `gitcrawl embed --number ... --limit 1` command to run. The TUI's `n` shortcut and "Enter on a member" also load vector neighbors for the selected row.
 
diff --git a/docs/commands.md b/docs/commands.md
index ffeb518d..b5acc14e 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -83,7 +83,7 @@ For an end-to-end first-run sequence that combines `status --json`, `doctor --js
 | `gitcrawl threads owner/repo [--include-closed --numbers --limit --json]` | List threads from local cache | — |
 | `gitcrawl search owner/repo --query <text> [--scope threads\|code\|all --mode keyword\|semantic\|hybrid --limit --json]` | Local thread/source search (direct mode) | [Search](/search/) |
 | `gitcrawl search issues\|prs <query> -R owner/repo [--state --json --limit --sync-if-stale]` | Local search (`gh search` shape) | [Search](/search/#gh-search-compatibility-mode) |
-| `gitcrawl neighbors owner/repo --number <ref> [--limit --threshold --json]` | Vector-similar threads to a specific issue/PR | [Clustering](/clustering/#find-similar-threads-neighbors) |
+| `gitcrawl neighbors owner/repo --number <ref> [--limit --threshold --include-closed --open-at --created-after --merged-after --json]` | Vector-similar threads to a specific issue/PR | [Clustering](/clustering/#find-similar-threads-neighbors) |
 
 ## Thread References
 
diff --git a/internal/cli/default_output_golden_test.go b/internal/cli/default_output_golden_test.go
new file mode 100644
index 00000000..109b0e0a
--- /dev/null
+++ b/internal/cli/default_output_golden_test.go
@@ -0,0 +1,227 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"flag"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/openclaw/gitcrawl/internal/store"
+)
+
+var updateDefaultOutputGolden = flag.Bool("update-default-output", false, "rewrite testdata/default_output golden files")
+
+// TestNeighborsDefaultOutputGolden pins what neighbors prints without any
+// time filter, so a new filter or field cannot silently change the rows,
+// order, or scores existing scripts and agents read.
+func TestNeighborsDefaultOutputGolden(t *testing.T) {
+	configPath := seedDefaultOutputStore(t)
+	run := func(t *testing.T, args ...string) string {
+		t.Helper()
+		app := New()
+		var stdout, stderr bytes.Buffer
+		app.Stdout = &stdout
+		app.Stderr = &stderr
+		if err := app.Run(context.Background(), append([]string{"--config", configPath}, args...)); err != nil {
+			t.Fatalf("%v: %v\n%s", args, err, stderr.String())
+		}
+		return stdout.String()
+	}
+
+	for _, tc := range []struct {
+		name string
+		args []string
+	}{
+		{"neighbors.json", []string{"neighbors", "openclaw/openclaw", "--number", "301", "--json"}},
+		{"neighbors.txt", []string{"neighbors", "openclaw/openclaw", "--number", "301"}},
+		{"neighbors-limit-threshold.json", []string{"neighbors", "openclaw/openclaw", "--number", "301", "--limit", "2", "--threshold", "0.95", "--json"}},
+		{"neighbors-include-closed.json", []string{"neighbors", "openclaw/openclaw", "--number", "301", "--include-closed", "--json"}},
+		{"neighbors-closed-source.json", []string{"neighbors", "openclaw/openclaw", "--number", "#303", "--include-closed", "--json"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got := normalizeDefaultOutput(t, run(t, tc.args...))
+			path := filepath.Join("testdata", "default_output", tc.name)
+			if *updateDefaultOutputGolden {
+				if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.WriteFile(path, []byte(got), 0o644); err != nil {
+					t.Fatal(err)
+				}
+				return
+			}
+			want, err := os.ReadFile(path)
+			if err != nil {
+				t.Fatalf("read golden (run with -update-default-output to create): %v", err)
+			}
+			if got != string(want) {
+				t.Fatalf("%v output changed\n--- want %s\n%s\n--- got\n%s", tc.args, path, want, got)
+			}
+		})
+	}
+}
+
+// Local bookkeeping clocks change on every run; GitHub clocks are fixed by the seed.
+var defaultOutputVolatileKeys = map[string]bool{
+	"first_pulled_at": true, "last_pulled_at": true, "updated_at": true,
+}
+
+var defaultOutputLocalClock = regexp.MustCompile(`"(` + strings.Join(func() []string {
+	keys := make([]string, 0, len(defaultOutputVolatileKeys))
+	for key := range defaultOutputVolatileKeys {
+		keys = append(keys, key)
+	}
+	return keys
+}(), "|") + `)": ("[^"]*"|[0-9.]+)`)
+
+func normalizeDefaultOutput(t *testing.T, out string) string {
+	t.Helper()
+	return defaultOutputLocalClock.ReplaceAllString(out, `"$1": "<local clock>"`)
+}
+
+// seedDefaultOutputStore seeds two topics with fixed GitHub clocks: gateway
+// rows (open, merged, and closed) and unrelated cache rows.
+func seedDefaultOutputStore(t *testing.T) string {
+	t.Helper()
+	ctx := context.Background()
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "config.toml")
+	dbPath := filepath.Join(dir, "gitcrawl.db")
+	if err := New().Run(ctx, []string{"--config", configPath, "init", "--db", dbPath}); err != nil {
+		t.Fatalf("init: %v", err)
+	}
+
+	embeddings := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var payload struct {
+			Input []string `json:"input"`
+		}
+		if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
+			t.Errorf("decode embeddings request: %v", err)
+		}
+		data := make([]map[string]any, 0, len(payload.Input))
+		for index := range payload.Input {
+			data = append(data, map[string]any{"index": index, "embedding": []float64{1, 0, 0}})
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"data": data})
+	}))
+	t.Cleanup(embeddings.Close)
+	t.Setenv("OPENAI_API_KEY", "test-openai-key")
+	t.Setenv("GITCRAWL_OPENAI_BASE_URL", embeddings.URL)
+
+	st, err := store.Open(ctx, dbPath)
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer st.Close()
+	const clock = "2026-01-01T00:00:00Z"
+	repoID, err := st.UpsertRepository(ctx, store.Repository{
+		Owner:        "openclaw",
+		Name:         "openclaw",
+		FullName:     "openclaw/openclaw",
+		GitHubRepoID: "12345",
+		RawJSON:      `{"full_name":"openclaw/openclaw"}`,
+		UpdatedAt:    clock,
+	})
+	if err != nil {
+		t.Fatalf("seed repository: %v", err)
+	}
+	// A complete open sync, then a targeted one that must not move the state clock.
+	for _, run := range []store.RunRecord{
+		{Scope: "open", StartedAt: "2026-03-20T09:00:00Z", FinishedAt: "2026-03-20T09:02:00Z", StatsJSON: `{"closed_sweep_through":"2026-03-20T09:00:00Z"}`},
+		{Scope: "numbers:301", StartedAt: "2026-03-21T09:00:00Z", FinishedAt: "2026-03-21T09:00:05Z", StatsJSON: `{}`},
+	} {
+		run.RepoID, run.Kind, run.Status = repoID, "sync", "success"
+		if _, err := st.RecordRun(ctx, run); err != nil {
+			t.Fatalf("seed sync run: %v", err)
+		}
+	}
+	type seed struct {
+		number                  int
+		kind, state, title      string
+		author, association     string
+		created, closed, merged string
+		draft                   bool
+		vector                  []float64
+	}
+	seeds := []seed{
+		{301, "issue", "open", "Gateway websocket stalls on reconnect", "alice", "NONE", "2026-03-01T10:00:00Z", "", "", false, []float64{1, 0, 0}},
+		{302, "pull_request", "open", "Fix gateway websocket reconnect stall", "bob", "CONTRIBUTOR", "2026-03-02T10:00:00Z", "", "", true, []float64{0.99, 0.1, 0}},
+		{303, "pull_request", "closed", "Gateway websocket reconnect backoff", "carol", "MEMBER", "2026-02-20T10:00:00Z", "2026-03-05T10:00:00Z", "2026-03-05T10:00:00Z", false, []float64{0.98, 0.15, 0.1}},
+		{304, "issue", "closed", "Gateway websocket drops messages", "dave", "NONE", "2026-01-10T10:00:00Z", "2026-02-01T10:00:00Z", "", false, []float64{0.97, 0.2, 0.1}},
+		{305, "issue", "open", "Gateway websocket timeout after sleep", "erin", "", "2026-03-10T10:00:00Z", "", "", false, []float64{0.96, 0.25, 0.1}},
+		{306, "issue", "open", "Portable cache grows without bound", "frank", "NONE", "2026-03-03T10:00:00Z", "", "", false, []float64{0, 1, 0}},
+		{307, "pull_request", "open", "Prune the portable cache", "grace", "CONTRIBUTOR", "2026-03-04T10:00:00Z", "", "", false, []float64{0.1, 0.99, 0}},
+	}
+	for _, s := range seeds {
+		path := "issues"
+		if s.kind == "pull_request" {
+			path = "pull"
+		}
+		body := s.title + " in the default output fixture."
+		id, err := st.UpsertThread(ctx, store.Thread{
+			RepoID:            repoID,
+			GitHubID:          "gh-" + strconv.Itoa(s.number),
+			Number:            s.number,
+			Kind:              s.kind,
+			State:             s.state,
+			Title:             s.title,
+			Body:              body,
+			AuthorLogin:       s.author,
+			AuthorType:        "User",
+			AuthorAssociation: s.association,
+			HTMLURL:           "https://github.com/openclaw/openclaw/" + path + "/" + strconv.Itoa(s.number),
+			LabelsJSON:        "[]",
+			AssigneesJSON:     "[]",
+			RawJSON:           "{}",
+			ContentHash:       "thread-" + strconv.Itoa(s.number),
+			IsDraft:           s.draft,
+			CreatedAtGitHub:   s.created,
+			UpdatedAtGitHub:   s.created,
+			ClosedAtGitHub:    s.closed,
+			MergedAtGitHub:    s.merged,
+			FirstPulledAt:     clock,
+			LastPulledAt:      clock,
+			UpdatedAt:         clock,
+		})
+		if err != nil {
+			t.Fatalf("seed thread %d: %v", s.number, err)
+		}
+		if _, err := st.UpsertDocument(ctx, store.Document{
+			ThreadID:   id,
+			Title:      s.title,
+			RawText:    s.title + "\n\n" + body,
+			DedupeText: strings.ToLower(s.title + " " + body),
+			UpdatedAt:  clock,
+		}); err != nil {
+			t.Fatalf("seed document %d: %v", s.number, err)
+		}
+		tasks, err := st.ListEmbeddingTasks(ctx, store.EmbeddingTaskOptions{
+			RepoID: repoID, Basis: "title_original", Model: "text-embedding-3-small",
+			Number: s.number, Limit: 1, IncludeClosed: true,
+		})
+		if err != nil || len(tasks) != 1 {
+			t.Fatalf("embedding task for %d = %#v, %v", s.number, tasks, err)
+		}
+		if err := st.UpsertThreadVector(ctx, store.ThreadVector{
+			ThreadID:    id,
+			Basis:       "title_original",
+			Model:       "text-embedding-3-small",
+			Dimensions:  3,
+			ContentHash: tasks[0].ContentHash,
+			Vector:      s.vector,
+			CreatedAt:   clock,
+			UpdatedAt:   clock,
+		}); err != nil {
+			t.Fatalf("seed vector %d: %v", s.number, err)
+		}
+	}
+	return configPath
+}
diff --git a/internal/cli/help.go b/internal/cli/help.go
index a0aee183..9fe75c02 100644
--- a/internal/cli/help.go
+++ b/internal/cli/help.go
@@ -258,7 +258,12 @@ Usage:
 	"neighbors": `gitcrawl neighbors lists vector-nearest local issue and pull request rows.
 
 Usage:
-  gitcrawl neighbors owner/repo --number ref [--limit N] [--include-closed] [--json]
+  gitcrawl neighbors owner/repo --number ref [--limit N] [--threshold N] [--include-closed] [--open-at time] [--created-after time|ref] [--merged-after time] [--json]
+
+Time filters take RFC 3339 times or YYYY-MM-DD dates (UTC); --created-after
+also takes an issue or pull request reference. --open-at and --merged-after
+imply --include-closed. state_as_of records the last complete sync-and-sweep
+start, not historical archive completeness. See the clustering guide for limits.
 `,
 	"runs": `gitcrawl runs lists local pipeline run history.
 
diff --git a/internal/cli/neighbors.go b/internal/cli/neighbors.go
index 5a7e734c..021f66ec 100644
--- a/internal/cli/neighbors.go
+++ b/internal/cli/neighbors.go
@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"strings"
+	"time"
 
 	"github.com/openclaw/gitcrawl/internal/config"
 	"github.com/openclaw/gitcrawl/internal/store"
@@ -19,8 +20,11 @@ func (a *App) runNeighbors(ctx context.Context, args []string) error {
 	limitRaw := fs.String("limit", "", "maximum neighbor rows")
 	thresholdRaw := fs.String("threshold", "", "minimum cosine score")
 	includeClosed := fs.Bool("include-closed", false, "include closed issue and pull request vectors")
+	openAtRaw := fs.String("open-at", "", "only rows open at this time")
+	createdAfterRaw := fs.String("created-after", "", "only rows created after this time or thread")
+	mergedAfterRaw := fs.String("merged-after", "", "only pull requests merged after this time")
 	jsonOut := fs.Bool("json", false, "write JSON output")
-	if err := fs.Parse(normalizeCommandArgs(args, map[string]bool{"number": true, "limit": true, "threshold": true})); err != nil {
+	if err := fs.Parse(normalizeCommandArgs(args, map[string]bool{"number": true, "limit": true, "threshold": true, "open-at": true, "created-after": true, "merged-after": true})); err != nil {
 		return usageErr(err)
 	}
 	a.applyCommandJSON(*jsonOut)
@@ -43,6 +47,22 @@ func (a *App) runNeighbors(ctx context.Context, args []string) error {
 	if err != nil {
 		return usageErr(err)
 	}
+	openAt, err := parseNeighborTime("open-at", *openAtRaw)
+	if err != nil {
+		return usageErr(err)
+	}
+	createdAfter, createdAfterNumber, err := parseNeighborCreatedAfter(*createdAfterRaw, owner+"/"+repoName)
+	if err != nil {
+		return usageErr(err)
+	}
+	mergedAfter, err := parseNeighborTime("merged-after", *mergedAfterRaw)
+	if err != nil {
+		return usageErr(err)
+	}
+	// Rows open at a past time or merged since, and often the source, may be closed now.
+	if !openAt.IsZero() || !mergedAfter.IsZero() {
+		*includeClosed = true
+	}
 	if limit <= 0 {
 		limit = 10
 	}
@@ -117,11 +137,15 @@ func (a *App) runNeighbors(ctx context.Context, args []string) error {
 		}
 	}
 	vectors, err := rt.Store.ListThreadVectorsFiltered(ctx, store.ThreadVectorQuery{
-		RepoID:        repo.ID,
-		Model:         targetVector.Model,
-		Basis:         targetVector.Basis,
-		Dimensions:    targetVector.Dimensions,
-		IncludeClosed: *includeClosed,
+		RepoID:             repo.ID,
+		Model:              targetVector.Model,
+		Basis:              targetVector.Basis,
+		Dimensions:         targetVector.Dimensions,
+		IncludeClosed:      *includeClosed,
+		OpenAt:             openAt,
+		CreatedAfter:       createdAfter,
+		CreatedAfterNumber: createdAfterNumber,
+		MergedAfter:        mergedAfter,
 	})
 	if err != nil {
 		return err
@@ -162,19 +186,21 @@ func (a *App) runNeighbors(ctx context.Context, args []string) error {
 		if !ok {
 			continue
 		}
-		neighbors = append(neighbors, map[string]any{
-			"thread_id": candidate.ThreadID,
-			"number":    thread.Number,
-			"kind":      thread.Kind,
-			"title":     thread.Title,
-			"score":     candidate.Score,
-		})
-	}
-	return a.writeOutput("neighbors", map[string]any{
+		neighbors = append(neighbors, neighborRow(thread, candidate.Score))
+	}
+	stateAsOf, err := rt.Store.StateAsOf(ctx, repo.ID)
+	if err != nil {
+		return err
+	}
+	payload := map[string]any{
 		"repository": repo.FullName,
 		"thread":     targetThread,
 		"neighbors":  neighbors,
-	}, true)
+	}
+	if !stateAsOf.IsZero() {
+		payload["state_as_of"] = stateAsOf.UTC().Format(time.RFC3339Nano)
+	}
+	return a.writeOutput("neighbors", payload, true)
 }
 
 func configuredNeighborTargetVector(ctx context.Context, rt localRuntime, repoID int64, number int, includeClosed bool) (store.Thread, store.ThreadVector, error) {
@@ -244,6 +270,62 @@ func neighborEmbeddingNeedsRefresh(ctx context.Context, st *store.Store, repoID
 	return len(tasks) > 0, nil
 }
 
+func neighborRow(thread store.Thread, score float64) map[string]any {
+	row := map[string]any{
+		"thread_id": thread.ID,
+		"number":    thread.Number,
+		"kind":      thread.Kind,
+		"state":     thread.State,
+		"title":     thread.Title,
+		"html_url":  thread.HTMLURL,
+		"is_draft":  thread.IsDraft,
+		"score":     score,
+	}
+	for key, value := range map[string]string{
+		"author_login":       thread.AuthorLogin,
+		"author_association": thread.AuthorAssociation,
+		"created_at_gh":      thread.CreatedAtGitHub,
+		"closed_at_gh":       thread.ClosedAtGitHub,
+		"merged_at_gh":       thread.MergedAtGitHub,
+		"closed_at_local":    thread.ClosedAtLocal,
+	} {
+		if value != "" {
+			row[key] = value
+		}
+	}
+	return row
+}
+
+func parseNeighborTime(name, value string) (time.Time, error) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return time.Time{}, nil
+	}
+	for _, layout := range []string{time.RFC3339Nano, time.DateOnly} {
+		if parsed, err := time.Parse(layout, value); err == nil {
+			return parsed, nil
+		}
+	}
+	return time.Time{}, fmt.Errorf("--%s expects an RFC 3339 time or YYYY-MM-DD date, got %q", name, value)
+}
+
+// parseNeighborCreatedAfter takes a time, or an issue or pull request
+// reference meaning "created after that thread".
+func parseNeighborCreatedAfter(value, repository string) (time.Time, int, error) {
+	at, timeErr := parseNeighborTime("created-after", value)
+	if timeErr == nil {
+		return at, 0, nil
+	}
+	if _, ok := parseThreadReference(value); ok {
+		number, err := parseOptionalThreadNumber(value, repository)
+		if err != nil {
+			return time.Time{}, 0, fmt.Errorf("--created-after: %w", err)
+		}
+		return time.Time{}, number, nil
+	}
+	return time.Time{}, 0, fmt.Errorf("--created-after expects an RFC 3339 time, YYYY-MM-DD date, or issue or pull request number, got %q", strings.TrimSpace(value))
+}
+
 func neighborEmbeddingRecoveryError(owner, repoName string, number int, includeClosed bool, cause error) error {
 	cmd := fmt.Sprintf("gitcrawl embed %s/%s --number %d --limit 1", owner, repoName, number)
 	if includeClosed {
diff --git a/internal/cli/neighbors_test.go b/internal/cli/neighbors_test.go
new file mode 100644
index 00000000..f4353098
--- /dev/null
+++ b/internal/cli/neighbors_test.go
@@ -0,0 +1,271 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"path/filepath"
+	"slices"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/openclaw/gitcrawl/internal/store"
+)
+
+type neighborsTestOutput struct {
+	Neighbors []map[string]any `json:"neighbors"`
+}
+
+func TestNeighborsRowsCarryThreadStateAndTimes(t *testing.T) {
+	configPath := seedNeighborTimelineStore(t)
+
+	out := runNeighborsTest(t, configPath, 200, "--include-closed")
+	rows := map[int]map[string]any{}
+	for _, row := range out.Neighbors {
+		rows[int(row["number"].(float64))] = row
+	}
+	open := rows[201]
+	if open["state"] != "open" || open["html_url"] != "https://github.com/openclaw/openclaw/pull/201" ||
+		open["author_login"] != "carol" || open["author_association"] != "CONTRIBUTOR" ||
+		open["created_at_gh"] != "2026-09-01T00:00:00Z" || open["is_draft"] != false {
+		t.Fatalf("open neighbor row = %#v", open)
+	}
+	if _, ok := open["merged_at_gh"]; ok {
+		t.Fatalf("open neighbor row should omit merged_at_gh: %#v", open)
+	}
+	merged := rows[202]
+	if merged["state"] != "closed" || merged["closed_at_gh"] != "2026-09-05T00:00:00Z" || merged["merged_at_gh"] != "2026-09-05T00:00:00Z" {
+		t.Fatalf("merged neighbor row = %#v", merged)
+	}
+	closed := rows[204]
+	if closed["state"] != "closed" || closed["closed_at_gh"] != "2026-09-12T00:00:00Z" {
+		t.Fatalf("closed neighbor row = %#v", closed)
+	}
+	if _, ok := closed["merged_at_gh"]; ok {
+		t.Fatalf("closed issue row should omit merged_at_gh: %#v", closed)
+	}
+}
+
+func TestNeighborsTimeFilters(t *testing.T) {
+	configPath := seedNeighborTimelineStore(t)
+
+	for _, tc := range []struct {
+		name   string
+		number int
+		args   []string
+		want   []int
+	}{
+		{name: "default open now", want: []int{201, 205}},
+		{name: "open at includes rows closed since", args: []string{"--open-at", "2026-09-10T12:00:00Z"}, want: []int{201, 204}},
+		// 2026-09-11T23:00Z: #204 closes an hour later, #203 is already open.
+		{name: "open at compares instants across offsets", args: []string{"--open-at", "2026-09-12T08:00:00+09:00"}, want: []int{201, 204, 203}},
+		{name: "open at includes a row created at T", args: []string{"--open-at", "2026-09-15"}, want: []int{201, 205, 203}},
+		{name: "open at excludes a row closed at T", args: []string{"--open-at", "2026-09-12"}, want: []int{201, 203}},
+		// Half a second after #205 was created and #204 closed; as text, "…00Z" sorts after "…00.5Z".
+		{name: "open at compares creation instants, not text", args: []string{"--open-at", "2026-09-15T00:00:00.5Z"}, want: []int{201, 205, 203}},
+		{name: "open at compares closure instants, not text", args: []string{"--open-at", "2026-09-12T00:00:00.5Z"}, want: []int{201, 203}},
+		{name: "created after open rows", args: []string{"--created-after", "2026-09-10"}, want: []int{205}},
+		{name: "created after with closed rows", args: []string{"--created-after", "2026-09-10", "--include-closed"}, want: []int{205, 203}},
+		{name: "created after excludes a row created at T", args: []string{"--created-after", "2026-09-11", "--include-closed"}, want: []int{205}},
+		{name: "created after compares instants, not text", args: []string{"--created-after", "2026-09-11T00:00:00.5Z", "--include-closed"}, want: []int{205}},
+		{name: "created after number", args: []string{"--created-after", "202"}, want: []int{205}},
+		// Numbers, not clocks: #203 and #204 rank after #202 whatever their created_at.
+		{name: "created after number with closed rows", args: []string{"--created-after", "#202", "--include-closed"}, want: []int{204, 205, 203}},
+		{name: "created after thread url", args: []string{"--created-after", "https://github.com/openclaw/openclaw/pull/202", "--include-closed"}, want: []int{204, 205, 203}},
+		{name: "merged after", args: []string{"--merged-after", "2026-09-10"}, want: []int{203}},
+		{name: "merged after excludes a merge at T", args: []string{"--merged-after", "2026-09-05"}, want: []int{203}},
+		// Half a second after #202 merged; as text, "…00Z" sorts after "…00.5Z".
+		{name: "merged after compares instants across offsets", args: []string{"--merged-after", "2026-09-05T09:00:00.5+09:00"}, want: []int{203}},
+		{name: "filters apply before limit", args: []string{"--merged-after", "2026-09-10", "--limit", "1"}, want: []int{203}},
+		{name: "closed source with open at", number: 204, args: []string{"--open-at", "2026-09-01T12:00:00Z"}, want: []int{202, 201}},
+		{name: "closed source with merged after", number: 202, args: []string{"--merged-after", "2026-09-10"}, want: []int{203}},
+		{name: "filters combine", args: []string{"--open-at", "2026-09-10T12:00:00Z", "--created-after", "2026-08-15"}, want: []int{201}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			number := tc.number
+			if number == 0 {
+				number = 200
+			}
+			out := runNeighborsTest(t, configPath, number, tc.args...)
+			var got []int
+			for _, row := range out.Neighbors {
+				got = append(got, int(row["number"].(float64)))
+			}
+			if !slices.Equal(got, tc.want) {
+				t.Fatalf("neighbors %v = %v, want %v", tc.args, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestNeighborsRejectsInvalidTimeFilters(t *testing.T) {
+	configPath := seedNeighborTimelineStore(t)
+	for _, flagName := range []string{"--open-at", "--created-after", "--merged-after"} {
+		app := New()
+		app.Stdout = &bytes.Buffer{}
+		app.Stderr = &bytes.Buffer{}
+		err := app.Run(context.Background(), []string{"--config", configPath, "neighbors", "openclaw/openclaw", "--number", "200", flagName, "last week", "--json"})
+		var cliErr *cliError
+		if !errors.As(err, &cliErr) || cliErr.code != 2 || !strings.Contains(err.Error(), "RFC 3339") {
+			t.Fatalf("%s invalid time error = %v, want usage error", flagName, err)
+		}
+	}
+}
+
+func TestNeighborsRejectsCreatedAfterFromAnotherRepository(t *testing.T) {
+	configPath := seedNeighborTimelineStore(t)
+	app := New()
+	app.Stdout = &bytes.Buffer{}
+	app.Stderr = &bytes.Buffer{}
+	err := app.Run(context.Background(), []string{"--config", configPath, "neighbors", "openclaw/openclaw", "--number", "200", "--created-after", "openclaw/gitcrawl#202", "--json"})
+	var cliErr *cliError
+	if !errors.As(err, &cliErr) || cliErr.code != 2 || !strings.Contains(err.Error(), "does not match") {
+		t.Fatalf("cross-repository --created-after error = %v, want usage error", err)
+	}
+}
+
+func TestNeighborsOmitsStateAsOfWithoutCompleteSync(t *testing.T) {
+	configPath := seedNeighborTimelineStore(t)
+	app := New()
+	var stdout bytes.Buffer
+	app.Stdout = &stdout
+	if err := app.Run(context.Background(), []string{"--config", configPath, "neighbors", "openclaw/openclaw", "--number", "200", "--json"}); err != nil {
+		t.Fatalf("neighbors: %v", err)
+	}
+	var out map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &out); err != nil {
+		t.Fatalf("decode neighbors output: %v", err)
+	}
+	if _, ok := out["state_as_of"]; ok {
+		t.Fatalf("state_as_of without a complete sync = %v, want omitted", out["state_as_of"])
+	}
+}
+
+func runNeighborsTest(t *testing.T, configPath string, number int, extra ...string) neighborsTestOutput {
+	t.Helper()
+	app := New()
+	var stdout bytes.Buffer
+	app.Stdout = &stdout
+	args := append([]string{"--config", configPath, "neighbors", "openclaw/openclaw", "--number", strconv.Itoa(number), "--threshold", "0.1", "--json"}, extra...)
+	if err := app.Run(context.Background(), args); err != nil {
+		t.Fatalf("neighbors %v: %v", extra, err)
+	}
+	var out neighborsTestOutput
+	if err := json.Unmarshal(stdout.Bytes(), &out); err != nil {
+		t.Fatalf("decode neighbors output %q: %v", stdout.String(), err)
+	}
+	return out
+}
+
+// seedNeighborTimelineStore seeds issue #200 (filed 2026-09-10) and similar
+// rows whose GitHub timestamps place them before, around, and after it.
+func seedNeighborTimelineStore(t *testing.T) string {
+	t.Helper()
+	t.Setenv("OPENAI_API_KEY", "")
+	ctx := context.Background()
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "config.toml")
+	dbPath := filepath.Join(dir, "gitcrawl.db")
+	if err := New().Run(ctx, []string{"--config", configPath, "init", "--db", dbPath}); err != nil {
+		t.Fatalf("init: %v", err)
+	}
+	st, err := store.Open(ctx, dbPath)
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer st.Close()
+	now := time.Now().UTC().Format(time.RFC3339Nano)
+	repoID, err := st.UpsertRepository(ctx, store.Repository{
+		Owner:        "openclaw",
+		Name:         "openclaw",
+		FullName:     "openclaw/openclaw",
+		GitHubRepoID: "12345",
+		RawJSON:      `{"full_name":"openclaw/openclaw"}`,
+		UpdatedAt:    now,
+	})
+	if err != nil {
+		t.Fatalf("seed repository: %v", err)
+	}
+	type seed struct {
+		number          int
+		kind, state     string
+		created, closed string
+		merged          string
+		vector          []float64
+	}
+	seeds := []seed{
+		{number: 200, kind: "issue", state: "open", created: "2026-09-10T00:00:00Z", vector: []float64{1, 0}},
+		{number: 201, kind: "pull_request", state: "open", created: "2026-09-01T00:00:00Z", vector: []float64{0.99, 0.14}},
+		{number: 202, kind: "pull_request", state: "closed", created: "2026-09-01T00:00:00Z", closed: "2026-09-05T00:00:00Z", merged: "2026-09-05T00:00:00Z", vector: []float64{0.98, 0.2}},
+		{number: 204, kind: "issue", state: "closed", created: "2026-08-01T00:00:00Z", closed: "2026-09-12T00:00:00Z", vector: []float64{0.97, 0.24}},
+		{number: 205, kind: "pull_request", state: "open", created: "2026-09-15T00:00:00Z", vector: []float64{0.96, 0.28}},
+		{number: 203, kind: "pull_request", state: "closed", created: "2026-09-11T00:00:00Z", closed: "2026-09-20T00:00:00Z", merged: "2026-09-20T00:00:00Z", vector: []float64{0.8, 0.6}},
+	}
+	for _, s := range seeds {
+		path := "issues"
+		if s.kind == "pull_request" {
+			path = "pull"
+		}
+		id, err := st.UpsertThread(ctx, store.Thread{
+			RepoID:            repoID,
+			GitHubID:          "gh-" + strconv.Itoa(s.number),
+			Number:            s.number,
+			Kind:              s.kind,
+			State:             s.state,
+			Title:             "Gateway websocket stalls " + strconv.Itoa(s.number),
+			Body:              "Gateway websocket stalls when messages arrive.",
+			AuthorLogin:       "carol",
+			AuthorType:        "User",
+			AuthorAssociation: "CONTRIBUTOR",
+			HTMLURL:           "https://github.com/openclaw/openclaw/" + path + "/" + strconv.Itoa(s.number),
+			LabelsJSON:        "[]",
+			AssigneesJSON:     "[]",
+			RawJSON:           "{}",
+			ContentHash:       "thread-" + strconv.Itoa(s.number),
+			CreatedAtGitHub:   s.created,
+			UpdatedAtGitHub:   s.created,
+			ClosedAtGitHub:    s.closed,
+			MergedAtGitHub:    s.merged,
+			UpdatedAt:         now,
+		})
+		if err != nil {
+			t.Fatalf("seed thread %d: %v", s.number, err)
+		}
+		if _, err := st.UpsertDocument(ctx, store.Document{
+			ThreadID:   id,
+			Title:      "Gateway websocket stalls " + strconv.Itoa(s.number),
+			RawText:    "Gateway websocket stalls when messages arrive.",
+			DedupeText: "gateway websocket stalls when messages arrive.",
+			UpdatedAt:  now,
+		}); err != nil {
+			t.Fatalf("seed document %d: %v", s.number, err)
+		}
+		tasks, err := st.ListEmbeddingTasks(ctx, store.EmbeddingTaskOptions{
+			RepoID:        repoID,
+			Basis:         "title_original",
+			Model:         "text-embedding-3-small",
+			Number:        s.number,
+			Limit:         1,
+			IncludeClosed: true,
+		})
+		if err != nil || len(tasks) != 1 {
+			t.Fatalf("embedding task for %d = %#v, %v", s.number, tasks, err)
+		}
+		if err := st.UpsertThreadVector(ctx, store.ThreadVector{
+			ThreadID:    id,
+			Basis:       "title_original",
+			Model:       "text-embedding-3-small",
+			Dimensions:  2,
+			ContentHash: tasks[0].ContentHash,
+			Vector:      s.vector,
+			CreatedAt:   now,
+			UpdatedAt:   now,
+		}); err != nil {
+			t.Fatalf("seed vector %d: %v", s.number, err)
+		}
+	}
+	return configPath
+}
diff --git a/internal/cli/testdata/default_output/neighbors-closed-source.json b/internal/cli/testdata/default_output/neighbors-closed-source.json
new file mode 100644
index 00000000..f6b676aa
--- /dev/null
+++ b/internal/cli/testdata/default_output/neighbors-closed-source.json
@@ -0,0 +1,96 @@
+{
+  "neighbors": [
+    {
+      "author_association": "NONE",
+      "author_login": "dave",
+      "closed_at_gh": "2026-02-01T10:00:00Z",
+      "created_at_gh": "2026-01-10T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/issues/304",
+      "is_draft": false,
+      "kind": "issue",
+      "number": 304,
+      "score": 0.9986898915443064,
+      "state": "closed",
+      "thread_id": 4,
+      "title": "Gateway websocket drops messages"
+    },
+    {
+      "author_login": "erin",
+      "created_at_gh": "2026-03-10T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/issues/305",
+      "is_draft": false,
+      "kind": "issue",
+      "number": 305,
+      "score": 0.9947661602711793,
+      "state": "open",
+      "thread_id": 5,
+      "title": "Gateway websocket timeout after sleep"
+    },
+    {
+      "author_association": "CONTRIBUTOR",
+      "author_login": "bob",
+      "created_at_gh": "2026-03-02T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/pull/302",
+      "is_draft": true,
+      "kind": "pull_request",
+      "number": 302,
+      "score": 0.9936469814650217,
+      "state": "open",
+      "thread_id": 2,
+      "title": "Fix gateway websocket reconnect stall"
+    },
+    {
+      "author_association": "NONE",
+      "author_login": "alice",
+      "created_at_gh": "2026-03-01T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/issues/301",
+      "is_draft": false,
+      "kind": "issue",
+      "number": 301,
+      "score": 0.9834976359705773,
+      "state": "open",
+      "thread_id": 1,
+      "title": "Gateway websocket stalls on reconnect"
+    },
+    {
+      "author_association": "CONTRIBUTOR",
+      "author_login": "grace",
+      "created_at_gh": "2026-03-04T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/pull/307",
+      "is_draft": false,
+      "kind": "pull_request",
+      "number": 307,
+      "score": 0.24861346014121793,
+      "state": "open",
+      "thread_id": 7,
+      "title": "Prune the portable cache"
+    }
+  ],
+  "repository": "openclaw/openclaw",
+  "state_as_of": "2026-03-20T09:00:00Z",
+  "thread": {
+    "id": 3,
+    "repo_id": 1,
+    "github_id": "gh-303",
+    "number": 303,
+    "kind": "pull_request",
+    "state": "closed",
+    "title": "Gateway websocket reconnect backoff",
+    "body": "Gateway websocket reconnect backoff in the default output fixture.",
+    "author_login": "carol",
+    "author_type": "User",
+    "author_association": "MEMBER",
+    "html_url": "https://github.com/openclaw/openclaw/pull/303",
+    "labels_json": "[]",
+    "assignees_json": "[]",
+    "content_hash": "thread-303",
+    "is_draft": false,
+    "created_at_gh": "2026-02-20T10:00:00Z",
+    "updated_at_gh": "2026-02-20T10:00:00Z",
+    "closed_at_gh": "2026-03-05T10:00:00Z",
+    "merged_at_gh": "2026-03-05T10:00:00Z",
+    "first_pulled_at": "<local clock>",
+    "last_pulled_at": "<local clock>",
+    "updated_at": "<local clock>"
+  }
+}
diff --git a/internal/cli/testdata/default_output/neighbors-include-closed.json b/internal/cli/testdata/default_output/neighbors-include-closed.json
new file mode 100644
index 00000000..13e36ee5
--- /dev/null
+++ b/internal/cli/testdata/default_output/neighbors-include-closed.json
@@ -0,0 +1,83 @@
+{
+  "neighbors": [
+    {
+      "author_association": "CONTRIBUTOR",
+      "author_login": "bob",
+      "created_at_gh": "2026-03-02T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/pull/302",
+      "is_draft": true,
+      "kind": "pull_request",
+      "number": 302,
+      "score": 0.994937189022498,
+      "state": "open",
+      "thread_id": 2,
+      "title": "Fix gateway websocket reconnect stall"
+    },
+    {
+      "author_association": "MEMBER",
+      "author_login": "carol",
+      "closed_at_gh": "2026-03-05T10:00:00Z",
+      "created_at_gh": "2026-02-20T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/pull/303",
+      "is_draft": false,
+      "kind": "pull_request",
+      "merged_at_gh": "2026-03-05T10:00:00Z",
+      "number": 303,
+      "score": 0.9834976359705773,
+      "state": "closed",
+      "thread_id": 3,
+      "title": "Gateway websocket reconnect backoff"
+    },
+    {
+      "author_association": "NONE",
+      "author_login": "dave",
+      "closed_at_gh": "2026-02-01T10:00:00Z",
+      "created_at_gh": "2026-01-10T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/issues/304",
+      "is_draft": false,
+      "kind": "issue",
+      "number": 304,
+      "score": 0.9744438523975748,
+      "state": "closed",
+      "thread_id": 4,
+      "title": "Gateway websocket drops messages"
+    },
+    {
+      "author_login": "erin",
+      "created_at_gh": "2026-03-10T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/issues/305",
+      "is_draft": false,
+      "kind": "issue",
+      "number": 305,
+      "score": 0.9628445935334788,
+      "state": "open",
+      "thread_id": 5,
+      "title": "Gateway websocket timeout after sleep"
+    }
+  ],
+  "repository": "openclaw/openclaw",
+  "state_as_of": "2026-03-20T09:00:00Z",
+  "thread": {
+    "id": 1,
+    "repo_id": 1,
+    "github_id": "gh-301",
+    "number": 301,
+    "kind": "issue",
+    "state": "open",
+    "title": "Gateway websocket stalls on reconnect",
+    "body": "Gateway websocket stalls on reconnect in the default output fixture.",
+    "author_login": "alice",
+    "author_type": "User",
+    "author_association": "NONE",
+    "html_url": "https://github.com/openclaw/openclaw/issues/301",
+    "labels_json": "[]",
+    "assignees_json": "[]",
+    "content_hash": "thread-301",
+    "is_draft": false,
+    "created_at_gh": "2026-03-01T10:00:00Z",
+    "updated_at_gh": "2026-03-01T10:00:00Z",
+    "first_pulled_at": "<local clock>",
+    "last_pulled_at": "<local clock>",
+    "updated_at": "<local clock>"
+  }
+}
diff --git a/internal/cli/testdata/default_output/neighbors-limit-threshold.json b/internal/cli/testdata/default_output/neighbors-limit-threshold.json
new file mode 100644
index 00000000..8b35d118
--- /dev/null
+++ b/internal/cli/testdata/default_output/neighbors-limit-threshold.json
@@ -0,0 +1,54 @@
+{
+  "neighbors": [
+    {
+      "author_association": "CONTRIBUTOR",
+      "author_login": "bob",
+      "created_at_gh": "2026-03-02T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/pull/302",
+      "is_draft": true,
+      "kind": "pull_request",
+      "number": 302,
+      "score": 0.994937189022498,
+      "state": "open",
+      "thread_id": 2,
+      "title": "Fix gateway websocket reconnect stall"
+    },
+    {
+      "author_login": "erin",
+      "created_at_gh": "2026-03-10T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/issues/305",
+      "is_draft": false,
+      "kind": "issue",
+      "number": 305,
+      "score": 0.9628445935334788,
+      "state": "open",
+      "thread_id": 5,
+      "title": "Gateway websocket timeout after sleep"
+    }
+  ],
+  "repository": "openclaw/openclaw",
+  "state_as_of": "2026-03-20T09:00:00Z",
+  "thread": {
+    "id": 1,
+    "repo_id": 1,
+    "github_id": "gh-301",
+    "number": 301,
+    "kind": "issue",
+    "state": "open",
+    "title": "Gateway websocket stalls on reconnect",
+    "body": "Gateway websocket stalls on reconnect in the default output fixture.",
+    "author_login": "alice",
+    "author_type": "User",
+    "author_association": "NONE",
+    "html_url": "https://github.com/openclaw/openclaw/issues/301",
+    "labels_json": "[]",
+    "assignees_json": "[]",
+    "content_hash": "thread-301",
+    "is_draft": false,
+    "created_at_gh": "2026-03-01T10:00:00Z",
+    "updated_at_gh": "2026-03-01T10:00:00Z",
+    "first_pulled_at": "<local clock>",
+    "last_pulled_at": "<local clock>",
+    "updated_at": "<local clock>"
+  }
+}
diff --git a/internal/cli/testdata/default_output/neighbors.json b/internal/cli/testdata/default_output/neighbors.json
new file mode 100644
index 00000000..8b35d118
--- /dev/null
+++ b/internal/cli/testdata/default_output/neighbors.json
@@ -0,0 +1,54 @@
+{
+  "neighbors": [
+    {
+      "author_association": "CONTRIBUTOR",
+      "author_login": "bob",
+      "created_at_gh": "2026-03-02T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/pull/302",
+      "is_draft": true,
+      "kind": "pull_request",
+      "number": 302,
+      "score": 0.994937189022498,
+      "state": "open",
+      "thread_id": 2,
+      "title": "Fix gateway websocket reconnect stall"
+    },
+    {
+      "author_login": "erin",
+      "created_at_gh": "2026-03-10T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/issues/305",
+      "is_draft": false,
+      "kind": "issue",
+      "number": 305,
+      "score": 0.9628445935334788,
+      "state": "open",
+      "thread_id": 5,
+      "title": "Gateway websocket timeout after sleep"
+    }
+  ],
+  "repository": "openclaw/openclaw",
+  "state_as_of": "2026-03-20T09:00:00Z",
+  "thread": {
+    "id": 1,
+    "repo_id": 1,
+    "github_id": "gh-301",
+    "number": 301,
+    "kind": "issue",
+    "state": "open",
+    "title": "Gateway websocket stalls on reconnect",
+    "body": "Gateway websocket stalls on reconnect in the default output fixture.",
+    "author_login": "alice",
+    "author_type": "User",
+    "author_association": "NONE",
+    "html_url": "https://github.com/openclaw/openclaw/issues/301",
+    "labels_json": "[]",
+    "assignees_json": "[]",
+    "content_hash": "thread-301",
+    "is_draft": false,
+    "created_at_gh": "2026-03-01T10:00:00Z",
+    "updated_at_gh": "2026-03-01T10:00:00Z",
+    "first_pulled_at": "<local clock>",
+    "last_pulled_at": "<local clock>",
+    "updated_at": "<local clock>"
+  }
+}
diff --git a/internal/cli/testdata/default_output/neighbors.txt b/internal/cli/testdata/default_output/neighbors.txt
new file mode 100644
index 00000000..4cb403bf
--- /dev/null
+++ b/internal/cli/testdata/default_output/neighbors.txt
@@ -0,0 +1,55 @@
+neighbors
+{
+  "neighbors": [
+    {
+      "author_association": "CONTRIBUTOR",
+      "author_login": "bob",
+      "created_at_gh": "2026-03-02T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/pull/302",
+      "is_draft": true,
+      "kind": "pull_request",
+      "number": 302,
+      "score": 0.994937189022498,
+      "state": "open",
+      "thread_id": 2,
+      "title": "Fix gateway websocket reconnect stall"
+    },
+    {
+      "author_login": "erin",
+      "created_at_gh": "2026-03-10T10:00:00Z",
+      "html_url": "https://github.com/openclaw/openclaw/issues/305",
+      "is_draft": false,
+      "kind": "issue",
+      "number": 305,
+      "score": 0.9628445935334788,
+      "state": "open",
+      "thread_id": 5,
+      "title": "Gateway websocket timeout after sleep"
+    }
+  ],
+  "repository": "openclaw/openclaw",
+  "state_as_of": "2026-03-20T09:00:00Z",
+  "thread": {
+    "id": 1,
+    "repo_id": 1,
+    "github_id": "gh-301",
+    "number": 301,
+    "kind": "issue",
+    "state": "open",
+    "title": "Gateway websocket stalls on reconnect",
+    "body": "Gateway websocket stalls on reconnect in the default output fixture.",
+    "author_login": "alice",
+    "author_type": "User",
+    "author_association": "NONE",
+    "html_url": "https://github.com/openclaw/openclaw/issues/301",
+    "labels_json": "[]",
+    "assignees_json": "[]",
+    "content_hash": "thread-301",
+    "is_draft": false,
+    "created_at_gh": "2026-03-01T10:00:00Z",
+    "updated_at_gh": "2026-03-01T10:00:00Z",
+    "first_pulled_at": "<local clock>",
+    "last_pulled_at": "<local clock>",
+    "updated_at": "<local clock>"
+  }
+}
diff --git a/internal/store/runs.go b/internal/store/runs.go
index 9c63bdd4..7bbfbb3d 100644
--- a/internal/store/runs.go
+++ b/internal/store/runs.go
@@ -198,6 +198,39 @@ func (s *Store) ClosedSweepWatermark(ctx context.Context, repoID int64) (time.Ti
 	return value, nil
 }
 
+// StateAsOf returns the start of the newest successful complete open or all
+// list sync. This is a sweep watermark, not proof of a historical backfill:
+// legacy closed rows may predate sweep coverage. Targeted, limited, failed,
+// or since-bounded syncs do not move it. It is zero without a qualifying run.
+func (s *Store) StateAsOf(ctx context.Context, repoID int64) (time.Time, error) {
+	if !s.hasColumns(ctx, "sync_runs", "repo_id", "scope", "status", "stats_json") {
+		return time.Time{}, nil
+	}
+	var raw string
+	err := s.q().QueryRowContext(ctx, `
+		select json_extract(stats_json, '$.closed_sweep_through')
+		from sync_runs
+		where repo_id = ? and status in ('success', 'completed')
+		  and scope in ('open', 'all')
+		  and json_valid(stats_json)
+		  and json_type(case when json_valid(stats_json) then stats_json else '{}' end,
+		                '$.closed_sweep_through') = 'text'
+		order by julianday(json_extract(stats_json, '$.closed_sweep_through')) desc, id desc
+		limit 1
+	`, repoID).Scan(&raw)
+	if err == sql.ErrNoRows {
+		return time.Time{}, nil
+	}
+	if err != nil {
+		return time.Time{}, fmt.Errorf("read state as of: %w", err)
+	}
+	value, err := time.Parse(time.RFC3339Nano, raw)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("parse state as of %q: %w", raw, err)
+	}
+	return value, nil
+}
+
 func (s *Store) LastSuccessfulListSyncAt(ctx context.Context, repoID int64, state string) (time.Time, error) {
 	state = normalizedListSyncState(state)
 	if state == "" || !s.hasColumns(ctx, "sync_runs", "repo_id", "scope", "status", "finished_at") {
diff --git a/internal/store/vectors.go b/internal/store/vectors.go
index 85057f10..4afdfb44 100644
--- a/internal/store/vectors.go
+++ b/internal/store/vectors.go
@@ -8,6 +8,7 @@ import (
 	"errors"
 	"fmt"
 	"math"
+	"time"
 	"unicode"
 )
 
@@ -29,6 +30,15 @@ type ThreadVectorQuery struct {
 	Basis         string
 	Dimensions    int
 	IncludeClosed bool
+	// OpenAt keeps rows created at or before the time and not closed by then.
+	OpenAt time.Time
+	// CreatedAfter keeps rows created after the time.
+	CreatedAfter time.Time
+	// CreatedAfterNumber keeps rows numbered above it. GitHub numbers issues
+	// and pull requests in creation order, so no clock is involved.
+	CreatedAfterNumber int
+	// MergedAfter keeps pull requests merged after the time.
+	MergedAfter time.Time
 }
 
 func (s *Store) UpsertThreadVector(ctx context.Context, vector ThreadVector) error {
@@ -181,6 +191,24 @@ func threadVectorWhere(query ThreadVectorQuery) (string, []any) {
 		where += ` and tv.dimensions = ?`
 		args = append(args, query.Dimensions)
 	}
+	if !query.OpenAt.IsZero() {
+		at := query.OpenAt.UTC().Format(time.RFC3339Nano)
+		where += ` and julianday(t.created_at_gh) <= julianday(?)` +
+			` and (coalesce(t.closed_at_gh, '') = '' or julianday(t.closed_at_gh) > julianday(?))`
+		args = append(args, at, at)
+	}
+	if !query.CreatedAfter.IsZero() {
+		where += ` and julianday(t.created_at_gh) > julianday(?)`
+		args = append(args, query.CreatedAfter.UTC().Format(time.RFC3339Nano))
+	}
+	if !query.MergedAfter.IsZero() {
+		where += ` and julianday(t.merged_at_gh) > julianday(?)`
+		args = append(args, query.MergedAfter.UTC().Format(time.RFC3339Nano))
+	}
+	if query.CreatedAfterNumber > 0 {
+		where += ` and t.number > ?`
+		args = append(args, query.CreatedAfterNumber)
+	}
 	return where, args
 }
 
diff --git a/internal/store/vectors_where_test.go b/internal/store/vectors_where_test.go
new file mode 100644
index 00000000..34655e3e
--- /dev/null
+++ b/internal/store/vectors_where_test.go
@@ -0,0 +1,103 @@
+package store
+
+import (
+	"context"
+	"path/filepath"
+	"reflect"
+	"testing"
+	"time"
+)
+
+// threadVectorWhereBeforeTimeFilters is threadVectorWhere as it was before the
+// time and number filters. Callers that set none of them (search, cluster,
+// refresh, the TUI, and neighbors without the new flags) must keep this SQL.
+func threadVectorWhereBeforeTimeFilters(query ThreadVectorQuery) (string, []any) {
+	where := `t.repo_id = ?`
+	args := []any{query.RepoID}
+	if !query.IncludeClosed {
+		where += ` and t.state = 'open' and t.closed_at_local is null`
+	}
+	if query.Model != "" {
+		where += ` and tv.model = ?`
+		args = append(args, query.Model)
+	}
+	if query.Basis != "" {
+		where += ` and tv.basis = ?`
+		args = append(args, query.Basis)
+	}
+	if query.Dimensions > 0 {
+		where += ` and tv.dimensions = ?`
+		args = append(args, query.Dimensions)
+	}
+	return where, args
+}
+
+func TestThreadVectorWhereWithoutTimeFiltersIsUnchanged(t *testing.T) {
+	for _, includeClosed := range []bool{false, true} {
+		for _, model := range []string{"", "text-embedding-3-small"} {
+			for _, basis := range []string{"", "title_original"} {
+				for _, dimensions := range []int{0, 1024} {
+					query := ThreadVectorQuery{RepoID: 7, Model: model, Basis: basis, Dimensions: dimensions, IncludeClosed: includeClosed}
+					gotWhere, gotArgs := threadVectorWhere(query)
+					wantWhere, wantArgs := threadVectorWhereBeforeTimeFilters(query)
+					if gotWhere != wantWhere || !reflect.DeepEqual(gotArgs, wantArgs) {
+						t.Fatalf("threadVectorWhere(%+v) = %q %v, want %q %v", query, gotWhere, gotArgs, wantWhere, wantArgs)
+					}
+				}
+			}
+		}
+	}
+}
+
+func TestStateAsOfUsesNewestCompleteListSync(t *testing.T) {
+	ctx := context.Background()
+	st, err := Open(ctx, filepath.Join(t.TempDir(), "gitcrawl.db"))
+	if err != nil {
+		t.Fatalf("open store: %v", err)
+	}
+	defer st.Close()
+	repoID, err := st.UpsertRepository(ctx, Repository{Owner: "openclaw", Name: "gitcrawl", FullName: "openclaw/gitcrawl", RawJSON: "{}", UpdatedAt: "2026-04-26T00:00:00Z"})
+	if err != nil {
+		t.Fatalf("repo: %v", err)
+	}
+	otherRepoID, err := st.UpsertRepository(ctx, Repository{Owner: "openclaw", Name: "openclaw", FullName: "openclaw/openclaw", RawJSON: "{}", UpdatedAt: "2026-04-26T00:00:00Z"})
+	if err != nil {
+		t.Fatalf("repo: %v", err)
+	}
+	record := func(repoID int64, scope, status, started, stats string) {
+		t.Helper()
+		if _, err := st.RecordRun(ctx, RunRecord{RepoID: repoID, Kind: "sync", Scope: scope, Status: status, StartedAt: started, FinishedAt: started, StatsJSON: stats}); err != nil {
+			t.Fatalf("record run: %v", err)
+		}
+	}
+	check := func(want string) {
+		t.Helper()
+		got, err := st.StateAsOf(ctx, repoID)
+		if err != nil {
+			t.Fatalf("state as of: %v", err)
+		}
+		if want == "" && !got.IsZero() || want != "" && got.UTC().Format(time.RFC3339) != want {
+			t.Fatalf("state as of = %v, want %q", got, want)
+		}
+	}
+
+	check("")
+	// A limited or since-bounded open sync records no sweep.
+	record(repoID, "open", "success", "2026-09-01T00:00:00Z", `{"repository":"openclaw/gitcrawl"}`)
+	check("")
+	record(repoID, "open", "success", "2026-09-02T00:00:00Z", `{"closed_sweep_through":"2026-09-02T00:00:00Z"}`)
+	check("2026-09-02T00:00:00Z")
+	record(repoID, "all", "success", "2026-09-03T00:00:00+09:00", `{"closed_sweep_through":"2026-09-03T00:00:00+09:00"}`)
+	check("2026-09-02T15:00:00Z")
+	// None of these certify every row's state.
+	record(repoID, "numbers:1,2", "success", "2026-09-05T00:00:00Z", `{"closed_sweep_through":"2026-09-05T00:00:00Z"}`)
+	record(repoID, "closed", "success", "2026-09-05T00:00:00Z", `{"closed_sweep_through":"2026-09-05T00:00:00Z"}`)
+	record(repoID, "open", "checkpoint", "2026-09-05T00:00:00Z", `{"closed_sweep_through":"2026-09-05T00:00:00Z"}`)
+	record(repoID, "open", "failed", "2026-09-05T00:00:00Z", `{"closed_sweep_through":"2026-09-05T00:00:00Z"}`)
+	record(repoID, "open", "success", "2026-09-05T00:00:00Z", `not json`)
+	record(otherRepoID, "open", "success", "2026-09-05T00:00:00Z", `{"closed_sweep_through":"2026-09-05T00:00:00Z"}`)
+	check("2026-09-02T15:00:00Z")
+	// Ordered by instant, not by row id or text.
+	record(repoID, "open", "success", "2026-09-02T20:00:00-05:00", `{"closed_sweep_through":"2026-09-02T20:00:00-05:00"}`)
+	check("2026-09-03T01:00:00Z")
+}
diff --git a/internal/syncer/closed_sweep_test.go b/internal/syncer/closed_sweep_test.go
index f4d80d98..40d98f91 100644
--- a/internal/syncer/closed_sweep_test.go
+++ b/internal/syncer/closed_sweep_test.go
@@ -62,6 +62,9 @@ func TestDefaultClosedSweepPreservesOfflineCoverageAndFailureCheckpoint(t *testi
 		t.Fatal(err)
 	}
 	started := now
+	if got, err := st.StateAsOf(ctx, repo.ID); err != nil || !got.Equal(started) {
+		t.Fatalf("complete sync state_as_of=%v err=%v", got, err)
+	}
 	now = now.Add(40 * 24 * time.Hour)
 	client.closed, client.fail = true, errors.New("denied after partial page")
 	if _, err := s.Sync(ctx, opts); !errors.Is(err, client.fail) {
@@ -71,6 +74,9 @@ func TestDefaultClosedSweepPreservesOfflineCoverageAndFailureCheckpoint(t *testi
 	if err != nil || !watermark.Equal(started) {
 		t.Fatalf("failed sweep advanced watermark=%v err=%v", watermark, err)
 	}
+	if got, err := st.StateAsOf(ctx, repo.ID); err != nil || !got.Equal(started) {
+		t.Fatalf("failed sweep advanced state_as_of=%v err=%v", got, err)
+	}
 	threads, err := st.ListThreads(ctx, repo.ID, true)
 	if err != nil || len(threads) != 1 || threads[0].State != "open" {
 		t.Fatalf("partial response changed state=%+v err=%v", threads, err)
@@ -98,6 +104,9 @@ func TestDefaultClosedSweepPreservesOfflineCoverageAndFailureCheckpoint(t *testi
 	if stats.ClosedSweepThrough != now.Format(time.RFC3339Nano) {
 		t.Fatalf("completed watermark=%q", stats.ClosedSweepThrough)
 	}
+	if got, err := st.StateAsOf(ctx, repo.ID); err != nil || !got.Equal(now) {
+		t.Fatalf("complete retry state_as_of=%v err=%v", got, err)
+	}
 	if client.requests[0].State != "open" || client.requests[0].Since != "" ||
 		client.requests[2].State != "open" || client.requests[2].Since != "" {
 		t.Fatalf("default open listing changed: %+v", client.requests)
@@ -194,6 +203,14 @@ func TestClosedSweepPreservesExplicitScopeContracts(t *testing.T) {
 			if tc.name != "all" && stats.ClosedSweepThrough != "" {
 				t.Fatalf("restricted run advanced default coverage=%q", stats.ClosedSweepThrough)
 			}
+			repo, err := st.RepositoryByFullName(ctx, "fixture/repo")
+			if err != nil {
+				t.Fatal(err)
+			}
+			got, err := st.StateAsOf(ctx, repo.ID)
+			if err != nil || (tc.name == "all" && !got.Equal(now)) || (tc.name != "all" && !got.IsZero()) {
+				t.Fatalf("%s sync state_as_of=%v err=%v", tc.name, got, err)
+			}
 			switch tc.name {
 			case "since":
 				if len(client.requests) != 2 {