replen 1.0.0 → 1.0.1

package/dist/commands.js

@@ -254,6 +254,31 @@ export async function runCheckNew(argv) {
             // correct response (calm-cadence principle).
             const scope = r.scopedTo ? ` for ${r.scopedTo}` : "";
             console.log(`No new actionable matches${scope} since you last engaged.`);
+            return;
+        }
+        // Hook mode + hasNew=false: fall back to inventory state. check-new
+        // is cursor-based and goes silent the moment ANY prior call (including
+        // our own validation probes or a previous session) bumped the cursor
+        // past existing matches. That's right behaviour for "did anything
+        // change?", wrong for "should I tell the agent there's a queue worth
+        // surfacing?" — the user might never have seen these candidates.
+        //
+        // Resolve the cwd's GitHub remote, query the inventory scoped to it,
+        // and print a one-line status if anything's there. Output goes
+        // verbatim into the agent's opening context via Claude Code's
+        // SessionStart-hook stdout injection.
+        const cwdRepo = await detectCwdRepo();
+        if (!cwdRepo)
+            return; // not in a git repo, or no GitHub remote — silent
+        try {
+            const inv = await fetchInventoryStatus(cfg, cwdRepo);
+            if (inv && inv.count > 0) {
+                const top = inv.topRepo ? ` Top: ${inv.topRepo}${inv.topSimilarity ? ` (~${inv.topSimilarity}% match)` : ""}.` : "";
+                console.log(`Replen has ${inv.count} candidate${inv.count === 1 ? "" : "s"} queued for ${cwdRepo}.${top} Run /replen-match for full triage.`);
+            }
+        }
+        catch {
+            // Inventory query failed — silent, never disrupt a session.
         }
         return;
     }
@@ -408,3 +433,61 @@ function handleApiError(e) {
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+// Resolve the cwd's git origin remote into a GitHub owner/name, if the
+// remote is a GitHub URL (HTTPS, standard SSH, or a multi-account SSH
+// alias like github-personal). Returns null if not in a git repo or the
+// remote isn't GitHub. Used by the SessionStart hook to scope inventory
+// queries to the project the user just opened Claude Code in.
+async function detectCwdRepo() {
+    try {
+        const { execSync } = await import("node:child_process");
+        const url = execSync("git remote get-url origin", {
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf8",
+            timeout: 1500,
+        }).trim();
+        const m = url.match(/(?:github\.com|github-[a-z0-9_-]+)[:/]([^/]+)\/([^/?#]+?)(?:\.git)?$/i);
+        if (!m)
+            return null;
+        return `${m[1]}/${m[2]}`;
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchInventoryStatus(cfg, repo) {
+    // Hook mode is on the session-open critical path; cap latency hard.
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 3000);
+    try {
+        const url = new URL(cfg.base + "/api/inventory/today");
+        url.searchParams.set("repo", repo);
+        url.searchParams.set("limit", "5");
+        url.searchParams.set("days", "14");
+        const res = await fetch(url, {
+            headers: { "x-digest-token": cfg.token, accept: "application/json" },
+            signal: ctrl.signal,
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const cands = data.candidates ?? [];
+        if (cands.length === 0)
+            return null;
+        const top = cands[0];
+        // Pull the cosine % out of whyShortlisted if present
+        // (format: "...; semantic similarity: 58%").
+        const simMatch = top.whyShortlisted?.match(/semantic similarity:\s*(\d+)%/);
+        return {
+            count: cands.length,
+            topRepo: top.repo ?? null,
+            topSimilarity: simMatch ? Number(simMatch[1]) : null,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/discover-projects.js

@@ -1,9 +1,12 @@
 // Local-filesystem project discovery for day-1 onboarding.
 //
-// Walks the user's conventional repo roots (~/github/, ~/code/,
-// ~/projects/) for git repos, then for each one extracts:
+// Recursively walks a list of root dirs (provided by discover-roots.ts),
+// finds every git repo, and for each one extracts:
 //   - The repo's `owner/name` from `git remote get-url origin`
-//   - A slug (from the directory basename, normalised)
+//   - A slug derived from the GITHUB repo name (so a local folder named
+//     "drone" whose remote is acme/aegis registers with slug "aegis",
+//     matching what shows on GitHub). Falls back to dirname for repos
+//     without a GitHub remote.
 //   - A name (from package.json's `name` field if present, else slug)
 //   - Auto-suggested tags from the project's manifests
 //   - The primary language (best-effort, from manifest type)
@@ -11,16 +14,54 @@
 // Output is shaped for POST /api/projects/bulk on the server. No
 // network or LLM calls — pure local filesystem.
 //
-// Why local-FS instead of asking GitHub via PAT: skill-mode's whole
-// pitch is "no API keys to share with us." Auto-detect via GitHub
-// API requires a PAT; auto-detect via local git remotes requires
-// nothing the user doesn't already have. PAT becomes optional, only
-// needed if/when the user wants server-side handoff PRs.
+// Why local-FS instead of asking GitHub via PAT: the whole pitch is
+// "no API keys to share with us." Auto-detect via GitHub API requires
+// a PAT; auto-detect via local git remotes requires nothing the user
+// doesn't already have. PAT becomes optional, only needed if/when the
+// user wants server-side handoff PRs.
 import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { execSync } from "node:child_process";
-import { homedir } from "node:os";
-import { join } from "node:path";
-const SCAN_ROOTS = ["github", "code", "projects"]; // immediate children of ~
+import { join, basename } from "node:path";
+// Hard maximum directory depth to walk from each root. depth=0 is the
+// root itself, depth=1 its immediate children, etc. 4 covers the
+// "workspace dir with sibling repos" pattern (e.g. ~/projects/drone/
+// containing ~/projects/drone/flight-controller/.git, where the
+// flight-controller dir is at depth 2 from ~/projects).
+const MAX_DEPTH = 4;
+// Directory names to skip outright during the walk. Mix of: build
+// artifacts that pollute repo-counting, package caches that can be
+// huge, and macOS / Linux home subdirs that never contain user code.
+const EXCLUDE_NAMES = new Set([
+    "node_modules",
+    ".next",
+    "dist",
+    "build",
+    "target",
+    "vendor",
+    ".cache",
+    ".npm",
+    ".yarn",
+    ".pnpm-store",
+    ".turbo",
+    ".terraform",
+    ".venv",
+    "venv",
+    "__pycache__",
+    // macOS system / media dirs
+    "Library",
+    "Applications",
+    "System",
+    "Pictures",
+    "Movies",
+    "Music",
+    "Downloads",
+    "Public",
+    "Desktop",
+    // Linux equivalents
+    ".local",
+    ".config",
+    "snap",
+]);
 // Manifest-derived tag mappings. Each pattern matches a dep name (or
 // a substring) and yields one or more tags. Ordered by specificity:
 // more-specific patterns first so e.g. "next" doesn't accidentally
@@ -84,45 +125,131 @@ const DEP_TO_TAGS = [
     { match: /^albumentations$/, tags: ["augmentation"] },
     { match: /^scikit-learn$/, tags: ["ml"] },
 ];
-export function discoverProjects() {
-    const out = [];
-    const home = homedir();
-    for (const root of SCAN_ROOTS) {
-        const rootPath = join(home, root);
-        if (!existsSync(rootPath))
-            continue;
-        let entries;
-        try {
-            entries = readdirSync(rootPath);
-        }
-        catch {
-            continue;
-        }
-        for (const dirName of entries) {
-            if (dirName.startsWith(".") || dirName === "node_modules")
+/**
+ * Walk the given roots recursively (depth-capped, excluded dirs skipped)
+ * and return every git repo found, partitioned by whether it has a
+ * GitHub origin remote. Repos without a GitHub remote are counted but
+ * not registered — they're surfaced to the user as transparency rather
+ * than silently dropped.
+ *
+ * Deduplicates by absolute `localPath` (so overlapping roots like
+ * `~/projects` and `~/projects/drone` don't double-register the inner
+ * repos) and by `githubFullName` (so cloning the same repo to two
+ * paths doesn't create two project rows).
+ *
+ * Slug = the local directory basename (normalised). When two repos in
+ * the discovery result would share a slug (e.g. `flight-controller`
+ * under both `~/projects/drone/` and `~/work/sandbox/`), the second+
+ * gets `-<owner>` appended to disambiguate. Keeps slugs short for the
+ * common case while preventing server-side `uniq_profile_user_slug`
+ * collisions.
+ *
+ * Identity is `githubFullName` on the server side; slug is just the
+ * URL-safe display label. So a local `~/projects/drone/` whose remote
+ * is `acme/aegis` keeps slug `drone` (matching how you think of it
+ * locally) while still registering correctly against `acme/aegis` on
+ * the dashboard.
+ */
+export function discoverProjects(roots) {
+    const seenPaths = new Set();
+    const seenGithub = new Set();
+    const projects = [];
+    let nonGithubSkipped = 0;
+    const scannedRoots = Array.from(new Set(roots.filter(existsAndIsDir)));
+    for (const root of scannedRoots) {
+        for (const repoPath of walkForGitRepos(root, 0)) {
+            if (seenPaths.has(repoPath))
                 continue;
-            const localPath = join(rootPath, dirName);
-            try {
-                if (!statSync(localPath).isDirectory())
-                    continue;
-                if (!existsSync(join(localPath, ".git")))
-                    continue;
-            }
-            catch {
+            seenPaths.add(repoPath);
+            const githubFullName = readGitRemote(repoPath);
+            const dirName = basename(repoPath);
+            if (!githubFullName) {
+                nonGithubSkipped++;
                 continue;
             }
-            const githubFullName = readGitRemote(localPath);
-            if (!githubFullName)
-                continue; // No GitHub remote → skip; can't register
-            const { name, tags, primaryLanguage } = extractMetadata(localPath, dirName);
-            const slug = normaliseSlug(dirName);
-            out.push({ localPath, slug, name, githubFullName, tags, primaryLanguage });
+            if (seenGithub.has(githubFullName))
+                continue;
+            seenGithub.add(githubFullName);
+            const { name, tags, primaryLanguage } = extractMetadata(repoPath, dirName);
+            projects.push({
+                localPath: repoPath,
+                slug: normaliseSlug(dirName),
+                name,
+                githubFullName,
+                tags,
+                primaryLanguage,
+            });
         }
     }
-    return out;
+    // In-discovery slug disambiguation. Same-name dirs under different
+    // parents (e.g. `~/projects/drone/flight-controller` +
+    // `~/work/flight-controller`) would otherwise collide on the server's
+    // `uniq_profile_user_slug` index. Suffix the second+ occurrence with
+    // the GitHub owner so it remains unique per user.
+    disambiguateSlugs(projects);
+    return { projects, nonGithubSkipped, scannedRoots };
+}
+function disambiguateSlugs(projects) {
+    const counts = new Map();
+    for (const p of projects)
+        counts.set(p.slug, (counts.get(p.slug) ?? 0) + 1);
+    const used = new Set();
+    for (const p of projects) {
+        if ((counts.get(p.slug) ?? 0) <= 1 && !used.has(p.slug)) {
+            used.add(p.slug);
+            continue;
+        }
+        const owner = (p.githubFullName ?? "").split("/")[0] ?? "";
+        let candidate = normaliseSlug(`${p.slug}-${owner}`);
+        let n = 2;
+        while (used.has(candidate)) {
+            candidate = normaliseSlug(`${p.slug}-${owner}-${n++}`);
+        }
+        p.slug = candidate;
+        used.add(candidate);
+    }
+}
+/**
+ * Generator: yields the absolute path of every git repo found under
+ * `dir`, up to `MAX_DEPTH`. Stops recursing into a directory once a
+ * `.git/` is found there (treats it as a repo boundary — submodules
+ * and nested-clone edge cases aren't worth complicating the walker).
+ */
+function* walkForGitRepos(dir, depth) {
+    if (depth > MAX_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    // Is this dir itself a repo? Yield + stop recursing.
+    if (entries.some((e) => e.name === ".git" && (e.isDirectory() || e.isSymbolicLink()))) {
+        yield dir;
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        if (entry.name.startsWith("."))
+            continue;
+        if (EXCLUDE_NAMES.has(entry.name))
+            continue;
+        yield* walkForGitRepos(join(dir, entry.name), depth + 1);
+    }
+}
+function existsAndIsDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
 }
-function normaliseSlug(dirName) {
-    return dirName
+function normaliseSlug(name) {
+    return name
         .toLowerCase()
         .replace(/[^a-z0-9_-]/g, "-")
         .replace(/^-+|-+$/g, "")
@@ -144,9 +271,17 @@ function readGitRemote(repoPath) {
     catch {
         return null;
     }
-    // Match both HTTPS (https://github.com/owner/name[.git]) and SSH
-    // (git@github.com:owner/name[.git]) formats.
-    const m = url.match(/github\.com[:/]([^/]+)\/([^/?#]+?)(?:\.git)?$/i);
+    // Match three URL shapes that all resolve to GitHub:
+    //   1. HTTPS:                      https://github.com/owner/name[.git]
+    //   2. Standard SSH:               git@github.com:owner/name[.git]
+    //   3. SSH config alias for github: git@github-<alias>:owner/name[.git]
+    // Case (3) is a common multi-account-GitHub pattern (one ssh alias
+    // per identity, e.g. `github-personal`, `github-work`); the host
+    // portion is opaque to git, the ssh layer resolves it to github.com.
+    // Without this branch, those repos register as "non-GitHub" and get
+    // silently skipped — a confusing failure mode for users with that
+    // convention. Owner/name parsing is identical across all three shapes.
+    const m = url.match(/(?:github\.com|github-[a-z0-9_-]+)[:/]([^/]+)\/([^/?#]+?)(?:\.git)?$/i);
     if (!m)
         return null;
     return `${m[1]}/${m[2]}`;

package/dist/discover-roots.js

@@ -0,0 +1,169 @@
+// Layered project-root discovery. Tries cheap inference first, falls back
+// to interactive prompt if nothing works. Result is one or more root dirs
+// that the recursive walker in discover-projects.ts will then scan for
+// git repos.
+//
+// Order (cheapest / most-targeted first):
+//   1. Explicit --root flag(s)               → user-specified
+//   2. REPLEN_PROJECT_ROOTS env var          → scripted / dotfiles
+//   3. Saved ~/.replen/config.json roots     → previously confirmed
+//   4. cwd walk-up                           → "I'm in a repo right now"
+//   5. ~/.claude.json mining                 → "I use Claude Code regularly"
+//   6. Hardcoded ~/github, ~/code, ~/projects → conventional layout
+//   7. Interactive prompt                    → ask the user directly
+//
+// The orchestration in sync-projects.ts tries strategies in order and
+// keeps going until at least one git repo is found, then stops looking.
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { readConfig } from "./config.js";
+/** From explicit `--root <path>` CLI flag(s), or empty if not passed. */
+export function rootsFromFlag(flagValues) {
+    return flagValues.map(expandTilde).filter(existsAndIsDir);
+}
+/** From `REPLEN_PROJECT_ROOTS` env var (colon-separated). */
+export function rootsFromEnv() {
+    const env = process.env.REPLEN_PROJECT_ROOTS;
+    if (!env)
+        return [];
+    return env.split(":").map((s) => s.trim()).filter(Boolean).map(expandTilde).filter(existsAndIsDir);
+}
+/** From the user's persisted ~/.replen/config.json `projectRoots`. */
+export async function rootsFromConfig() {
+    const cfg = await readConfig();
+    if (!cfg?.projectRoots?.length)
+        return [];
+    return cfg.projectRoots.map(expandTilde).filter(existsAndIsDir);
+}
+/**
+ * If `npx replen` was invoked from inside a git repo (or one of its
+ * subdirs), walk up to find the repo root, then return its parent dir
+ * as a candidate root. This catches the common "I'm sitting in one of
+ * my projects when I install Replen" case.
+ *
+ * Stops at `homedir()` and at `/` to avoid walking into system dirs.
+ */
+export function rootsFromCwdWalkUp() {
+    const cwd = process.cwd();
+    const home = homedir();
+    let dir = cwd;
+    // Walk up until we find a .git/ or hit home/root.
+    while (dir !== "/" && dir !== home && dir.length > 1) {
+        if (existsSync(join(dir, ".git"))) {
+            const parent = dirname(dir);
+            // Only suggest the parent if it's still inside home — never offer
+            // "/" or anything above $HOME as a scan root.
+            if (parent.startsWith(home) && parent !== home)
+                return [parent];
+            return [];
+        }
+        dir = dirname(dir);
+    }
+    return [];
+}
+/**
+ * Read ~/.claude.json (Claude Code's per-user config) and extract the
+ * project cwds it tracks. Group by parent dir. Return parents that
+ * contain ≥2 Claude Code projects — these are very likely the user's
+ * actual repo roots.
+ *
+ * Why this is high-signal: Claude Code only adds an entry when the user
+ * opens it inside a real project, so the cwd list is curated by their
+ * actual usage. Far more accurate than guessing dir names.
+ */
+export function rootsFromClaudeJson() {
+    const claudePath = join(homedir(), ".claude.json");
+    if (!existsSync(claudePath))
+        return [];
+    let data;
+    try {
+        data = JSON.parse(readFileSync(claudePath, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (!data || typeof data !== "object")
+        return [];
+    const projects = data.projects;
+    if (!projects || typeof projects !== "object")
+        return [];
+    const parentCounts = new Map();
+    for (const path of Object.keys(projects)) {
+        if (!path.startsWith("/"))
+            continue;
+        const parent = dirname(path);
+        if (!parent.startsWith(homedir()))
+            continue;
+        parentCounts.set(parent, (parentCounts.get(parent) ?? 0) + 1);
+    }
+    return Array.from(parentCounts.entries())
+        .filter(([, n]) => n >= 2)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([parent]) => parent)
+        .filter(existsAndIsDir);
+}
+/** Conventional layout: ~/github, ~/code, ~/projects. */
+export function rootsFromHardcoded() {
+    return ["github", "code", "projects", "Code", "Projects", "dev", "src", "work"]
+        .map((n) => join(homedir(), n))
+        .filter(existsAndIsDir);
+}
+/**
+ * Last-resort interactive prompt. Asks the user where they keep their
+ * code, with a sensible default. Returns null if the user is in a
+ * non-interactive context (stdin not a TTY) or hits Ctrl-C.
+ */
+export async function promptForRoot() {
+    if (!process.stdin.isTTY)
+        return null;
+    const home = homedir();
+    // Suggest the most common parent of any folder we know about, falling
+    // back to home itself.
+    const suggestion = pickPromptSuggestion() ?? home;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`\n  Where do you keep your code? [${suggestion}]: `)).trim();
+        const chosen = answer || suggestion;
+        const expanded = expandTilde(chosen);
+        if (!existsAndIsDir(expanded)) {
+            console.warn(`  ✗ Not a directory: ${expanded}`);
+            return null;
+        }
+        return expanded;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        rl.close();
+    }
+}
+function pickPromptSuggestion() {
+    const fromCwd = rootsFromCwdWalkUp();
+    if (fromCwd[0])
+        return fromCwd[0];
+    const fromClaude = rootsFromClaudeJson();
+    if (fromClaude[0])
+        return fromClaude[0];
+    const fromHard = rootsFromHardcoded();
+    if (fromHard[0])
+        return fromHard[0];
+    return null;
+}
+function expandTilde(p) {
+    if (p === "~" || p.startsWith("~/")) {
+        return p === "~" ? homedir() : join(homedir(), p.slice(2));
+    }
+    return resolve(p);
+}
+function existsAndIsDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/first-ingest.js

@@ -0,0 +1,140 @@
+// First-time ingest streamer used by `npx replen` after install.
+//
+// Triggers a pipeline run and tails progress until the discovered pool
+// is ready (event signal: `fetch_done` with "Discovered pool" message,
+// or candidates count crosses 0). Then exits cleanly. Stages 1+2 and
+// the scouted-pool fetcher continue server-side in the background;
+// the user can do `npx replen progress` later if they want to watch
+// the rest, or just open Claude Code and the agent will find whatever
+// landed.
+//
+// Why exit early instead of waiting for full pipeline completion: a
+// fresh install with 30+ projects can take 5-10 min for Stage 1+2
+// per-project LLM work to finish. The user shouldn't sit at a blank
+// terminal — they want to know "is there something I can look at now?"
+// and the answer becomes yes once the discovered pool lands (typically
+// 30-60s in).
+//
+// Tolerant of rate-limit and in-flight responses; never fails the
+// install flow on its own — worst case prints a "you can run
+// `npx replen progress` later" hint and returns.
+import { apiGet, apiPost } from "./api.js";
+const POLL_INTERVAL_MS = 2500;
+// Absolute cap on how long we sit in the streamer. Discovered pool
+// usually lands inside 60s but giving generous headroom for slow
+// fetcher tails. If we hit this, we exit with a hint rather than
+// blocking the install flow.
+const MAX_WAIT_MS = 180_000;
+export async function runFirstIngest(cfg) {
+    console.log("");
+    console.log("  Pulling first batch of candidates from your sources…");
+    console.log("  (This takes about a minute. You can `^C` here — ingest continues server-side.)");
+    console.log("");
+    // Step 1: trigger a run. Tolerant of in-flight / rate-limit.
+    let triggered = null;
+    try {
+        triggered = await apiPost(cfg, "/api/mcp/run-now", {});
+    }
+    catch (e) {
+        // Surface but don't fail install — the cron scheduler will pick
+        // up the new projects on its next tick.
+        console.log(`  · Couldn't trigger an immediate run (${e.message.slice(0, 80)}).`);
+        console.log(`    The cron scheduler will catch up shortly. Open Claude Code in a tracked repo`);
+        console.log(`    in a few minutes and the agent will mention any new matches.`);
+        return;
+    }
+    if (!triggered.ok && triggered.status !== "in_flight") {
+        console.log(`  · Run not started: ${triggered.reason ?? triggered.status}`);
+        console.log(`    The next scheduled run will pick up the new projects.`);
+        return;
+    }
+    // Step 2: poll status, print events, exit when discovered pool ready.
+    let since = 0;
+    let firstTick = true;
+    let lastCandidates = 0;
+    let startedAt = Date.now();
+    let discoveredReadyAnnounced = false;
+    while (true) {
+        if (Date.now() - startedAt > MAX_WAIT_MS) {
+            console.log("");
+            console.log("  · Ingest still going — exiting the streamer so you're not blocked.");
+            console.log("    Run `npx replen progress` to keep watching, or just open Claude Code.");
+            return;
+        }
+        let status;
+        try {
+            status = await apiGet(cfg, "/api/mcp/status", since ? { since } : undefined);
+        }
+        catch (e) {
+            console.log(`  · Lost connection to status endpoint: ${e.message.slice(0, 80)}`);
+            console.log(`    Ingest still running. Open Claude Code shortly to see matches.`);
+            return;
+        }
+        if (firstTick) {
+            const phase = status.phase ?? "starting";
+            console.log(`  Run #${status.runId ?? "?"} · ${status.inFlight ? `running · phase=${phase}` : "idle"}`);
+            firstTick = false;
+        }
+        for (const ev of status.events ?? []) {
+            console.log(`  ${marker(ev.kind)} ${ev.message}`);
+            if (ev.id > since)
+                since = ev.id;
+            // The Phase-1 completion signal: pipeline emits a `fetch_done`
+            // event whose message starts with "Discovered pool:". Once we
+            // see that, the discovered candidates are persisted and visible
+            // to replen_match.
+            if (ev.kind === "fetch_done" &&
+                ev.message.startsWith("Discovered pool:") &&
+                !discoveredReadyAnnounced) {
+                discoveredReadyAnnounced = true;
+                // Don't exit immediately — let the next poll catch any inline
+                // events so the user sees a coherent end state, then bail.
+            }
+        }
+        // Fallback signal: if candidates count crossed 0, the discovered
+        // pool is functionally ready even if the event ordering didn't
+        // emit the expected marker. Belt + suspenders.
+        if (!discoveredReadyAnnounced && (status.candidates ?? 0) > lastCandidates && (status.candidates ?? 0) > 0) {
+            discoveredReadyAnnounced = true;
+        }
+        lastCandidates = status.candidates ?? lastCandidates;
+        // If the whole pipeline already finished (e.g. existing user with
+        // cached vectors — runs end fast), exit cleanly.
+        if (!status.inFlight) {
+            console.log("");
+            console.log(`  ✓ Ingest complete · ${status.candidates ?? 0} candidate(s) in inventory.`);
+            return;
+        }
+        // If discovered pool is ready, exit and let the rest run server-
+        // side. Stage 1+2 + scouted pool take much longer; no point making
+        // the user watch them.
+        if (discoveredReadyAnnounced) {
+            console.log("");
+            console.log(`  ✓ First candidates ready (${status.candidates ?? "?"} so far).`);
+            console.log(`    Per-project relevance refinement continues in the background.`);
+            console.log(`    Run \`npx replen progress\` later to watch, or just open Claude Code.`);
+            return;
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+}
+function marker(kind) {
+    switch (kind) {
+        case "fetch_start":
+        case "fetch_done":
+            return "›";
+        case "scan":
+            return "·";
+        case "match":
+            return "✓";
+        case "skip":
+            return "·";
+        case "error":
+            return "✗";
+        default:
+            return "·";
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}