@unbrained/pm-cli 2026.5.29 → 2026.5.31

package/dist/core/search/background-refresh.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared lock id for any process that rewrites the local vector store. Reindex
+ * and the background mutation-refresh worker both acquire this so they never
+ * write concurrently and corrupt the store. Exported so `pm reindex` reuses the
+ * same id rather than duplicating the literal.
+ */
+export declare const REINDEX_LOCK_ID = "reindex";
+/**
+ * Mutation search refresh runs inline (blocking) under test runners, inside the
+ * background worker child itself, or when explicitly requested. Otherwise the
+ * semantic refresh is dispatched to a detached child so mutations return without
+ * waiting on embeddings. Mirrors the telemetry-flush inline gate so the full test
+ * suite stays deterministic.
+ */
+export declare function shouldRunSearchRefreshInForeground(): boolean;
+declare function pendingQueuePath(pmRoot: string): string;
+declare function acquireQueueGate(pmRoot: string): boolean;
+declare function releaseQueueGate(pmRoot: string): void;
+/** Merge mutated item ids into the persistent pending-refresh queue. */
+export declare function enqueuePendingRefreshIds(pmRoot: string, itemIds: string[]): Promise<void>;
+/** Atomically read and clear the pending-refresh queue, returning drained ids. */
+export declare function drainPendingRefreshIds(pmRoot: string): Promise<string[]>;
+/**
+ * Enqueue mutated ids and dispatch a detached worker child to refresh semantic
+ * embeddings without blocking the mutation. The reindex lock the worker acquires
+ * serializes concurrent refreshes, so the spawn itself stays unconditional and
+ * cheap; a worker that loses the lock exits and its ids are drained by the holder.
+ */
+export declare function scheduleBackgroundSemanticRefresh(pmRoot: string, itemIds: string[]): Promise<void>;
+export interface SemanticRefreshWorkerResult {
+    processed: string[];
+    rounds: number;
+    warnings: string[];
+}
+type SemanticRefreshFn = (pmRoot: string, itemIds: string[]) => Promise<{
+    refreshed: string[];
+    skipped: string[];
+    warnings: string[];
+}>;
+/**
+ * Drain the pending queue and refresh semantic vectors under the reindex lock so
+ * the local vector store is never rewritten concurrently. If the lock is held by
+ * another worker we exit immediately — that holder drains our enqueued ids. After
+ * releasing we re-check the queue once and re-dispatch if a sibling enqueued ids
+ * during our final window, guaranteeing eventual processing.
+ */
+export declare function runSemanticRefreshWorker(pmRoot: string, refresh: SemanticRefreshFn): Promise<SemanticRefreshWorkerResult>;
+export declare const _backgroundRefreshInternals: {
+    pendingQueuePath: typeof pendingQueuePath;
+    acquireQueueGate: typeof acquireQueueGate;
+    releaseQueueGate: typeof releaseQueueGate;
+};
+export {};

package/dist/core/search/background-refresh.js

@@ -0,0 +1,286 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d8990236-9b78-570d-bafa-5da0ce621293")}catch(e){}}();
+import { spawn } from "node:child_process";
+import { mkdirSync, rmSync, statSync } from "node:fs";
+import path from "node:path";
+import { pathExists, readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
+import { acquireLock } from "../lock/lock.js";
+import { resolvePmPackageRootFromModule } from "../packages/root.js";
+import { readSettings } from "../store/settings.js";
+import { toErrorMessage } from "../shared/primitives.js";
+import { resolveSettingsWithSemanticRuntimeDefaults } from "./semantic-defaults.js";
+/**
+ * Shared lock id for any process that rewrites the local vector store. Reindex
+ * and the background mutation-refresh worker both acquire this so they never
+ * write concurrently and corrupt the store. Exported so `pm reindex` reuses the
+ * same id rather than duplicating the literal.
+ */
+export const REINDEX_LOCK_ID = "reindex";
+const PENDING_QUEUE_REL_PATH = "search/pending-refresh.json";
+const PENDING_QUEUE_GATE_REL_PATH = "search/pending-refresh.gate.lock";
+const PENDING_QUEUE_GATE_STALE_MS = 30_000;
+// Bounded reindex-lock retry for the background worker (~3.2s worst case).
+const LOCK_ACQUIRE_ATTEMPTS = 8;
+const LOCK_ACQUIRE_BACKOFF_MS = 400;
+const SEARCH_REFRESH_INLINE_ENV = "PM_SEARCH_REFRESH_INLINE";
+const SEARCH_REFRESH_CHILD_ENV = "PM_SEARCH_REFRESH_CHILD";
+function parseBooleanTrueLike(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+/**
+ * Mutation search refresh runs inline (blocking) under test runners, inside the
+ * background worker child itself, or when explicitly requested. Otherwise the
+ * semantic refresh is dispatched to a detached child so mutations return without
+ * waiting on embeddings. Mirrors the telemetry-flush inline gate so the full test
+ * suite stays deterministic.
+ */
+export function shouldRunSearchRefreshInForeground() {
+    if (parseBooleanTrueLike(process.env[SEARCH_REFRESH_INLINE_ENV])) {
+        return true;
+    }
+    if (parseBooleanTrueLike(process.env[SEARCH_REFRESH_CHILD_ENV])) {
+        return true;
+    }
+    const nodeEnv = (process.env.NODE_ENV ?? "").trim().toLowerCase();
+    return (typeof process.env.VITEST === "string" ||
+        typeof process.env.VITEST_WORKER_ID === "string" ||
+        nodeEnv === "test");
+}
+function pendingQueuePath(pmRoot) {
+    return path.join(pmRoot, PENDING_QUEUE_REL_PATH);
+}
+function pendingQueueGatePath(pmRoot) {
+    return path.join(pmRoot, PENDING_QUEUE_GATE_REL_PATH);
+}
+function acquireQueueGate(pmRoot) {
+    const gatePath = pendingQueueGatePath(pmRoot);
+    try {
+        if (Date.now() - statSync(gatePath).mtimeMs < PENDING_QUEUE_GATE_STALE_MS) {
+            return false;
+        }
+        rmSync(gatePath, { recursive: true, force: true });
+    }
+    catch {
+        // Missing gate is the common case; fall through to create it.
+    }
+    try {
+        mkdirSync(path.dirname(gatePath), { recursive: true });
+        mkdirSync(gatePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function releaseQueueGate(pmRoot) {
+    try {
+        rmSync(pendingQueueGatePath(pmRoot), { recursive: true, force: true });
+    }
+    catch {
+        // Best effort; a stale gate self-heals after PENDING_QUEUE_GATE_STALE_MS.
+    }
+}
+async function withQueueGate(pmRoot, fn, fallback) {
+    // Briefly serialize read-modify-write access to the pending queue across the
+    // mutation process and the worker child. Acquisition is best effort; if a
+    // healthy gate is held we skip rather than risk a torn queue.
+    for (let attempt = 0; attempt < 50; attempt += 1) {
+        if (acquireQueueGate(pmRoot)) {
+            try {
+                return await fn();
+            }
+            finally {
+                releaseQueueGate(pmRoot);
+            }
+        }
+        await delay(20);
+    }
+    return fallback;
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms).unref?.();
+    });
+}
+async function readPendingQueueIds(pmRoot) {
+    const raw = await readFileIfExists(pendingQueuePath(pmRoot));
+    if (!raw || raw.trim().length === 0) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.ids)) {
+            return [];
+        }
+        return parsed.ids.filter((id) => typeof id === "string" && id.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+async function writePendingQueueIds(pmRoot, ids) {
+    await writeFileAtomic(pendingQueuePath(pmRoot), `${JSON.stringify({ ids })}\n`);
+}
+/** Merge mutated item ids into the persistent pending-refresh queue. */
+export async function enqueuePendingRefreshIds(pmRoot, itemIds) {
+    const incoming = itemIds.filter((id) => typeof id === "string" && id.trim().length > 0);
+    if (incoming.length === 0) {
+        return;
+    }
+    const mergeIncoming = async () => {
+        const existing = await readPendingQueueIds(pmRoot);
+        const merged = [...new Set([...existing, ...incoming])].sort((left, right) => left.localeCompare(right));
+        await writePendingQueueIds(pmRoot, merged);
+    };
+    const gated = await withQueueGate(pmRoot, async () => {
+        await mergeIncoming();
+        return true;
+    }, false);
+    if (!gated) {
+        // The gate stayed contended past the retry budget. Never silently drop a
+        // mutation's refresh work: fall back to a best-effort unguarded merge.
+        // writeFileAtomic keeps the file valid; the only risk is losing a concurrent
+        // writer's delta, which its own next dispatch and the vector_index_stale
+        // warning both recover.
+        await mergeIncoming();
+    }
+}
+/** Atomically read and clear the pending-refresh queue, returning drained ids. */
+export async function drainPendingRefreshIds(pmRoot) {
+    return withQueueGate(pmRoot, async () => {
+        const ids = await readPendingQueueIds(pmRoot);
+        if (ids.length > 0) {
+            await writePendingQueueIds(pmRoot, []);
+        }
+        return ids;
+    }, []);
+}
+function searchRefreshRunnerPath() {
+    return path.join(resolvePmPackageRootFromModule(import.meta.url, ["../../.."]), "dist", "cli", "search-refresh.js");
+}
+/**
+ * Spawn the detached refresh worker child for this pm root. Best effort: a
+ * failed dispatch must never keep the CLI alive or fail a mutation; the next
+ * mutation re-dispatches and `vector_index_stale` warns about the catch-up
+ * window in the meantime.
+ */
+function dispatchRefreshChild(pmRoot) {
+    try {
+        const child = spawn(process.execPath, [searchRefreshRunnerPath()], {
+            detached: true,
+            stdio: "ignore",
+            env: {
+                ...process.env,
+                PM_PATH: pmRoot,
+                [SEARCH_REFRESH_CHILD_ENV]: "1",
+            },
+        });
+        // A detached child can emit an async 'error' event (e.g. spawn EAGAIN/ENOENT,
+        // resource limits). Swallow it so it never becomes an unhandled error that
+        // crashes the parent CLI; dispatch is best effort.
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // Best effort — see doc comment above.
+    }
+}
+/**
+ * Enqueue mutated ids and dispatch a detached worker child to refresh semantic
+ * embeddings without blocking the mutation. The reindex lock the worker acquires
+ * serializes concurrent refreshes, so the spawn itself stays unconditional and
+ * cheap; a worker that loses the lock exits and its ids are drained by the holder.
+ */
+export async function scheduleBackgroundSemanticRefresh(pmRoot, itemIds) {
+    await enqueuePendingRefreshIds(pmRoot, itemIds);
+    dispatchRefreshChild(pmRoot);
+}
+/**
+ * Drain the pending queue and refresh semantic vectors under the reindex lock so
+ * the local vector store is never rewritten concurrently. If the lock is held by
+ * another worker we exit immediately — that holder drains our enqueued ids. After
+ * releasing we re-check the queue once and re-dispatch if a sibling enqueued ids
+ * during our final window, guaranteeing eventual processing.
+ */
+export async function runSemanticRefreshWorker(pmRoot, refresh) {
+    const warnings = [];
+    const processed = [];
+    if (!(await pathExists(pmRoot))) {
+        return { processed, rounds: 0, warnings };
+    }
+    let settings;
+    try {
+        settings = resolveSettingsWithSemanticRuntimeDefaults(await readSettings(pmRoot)).settings;
+    }
+    catch (error) {
+        return { processed, rounds: 0, warnings: [`search_background_refresh_settings_read_failed:${toErrorMessage(error)}`] };
+    }
+    // Retry the reindex lock with backoff rather than exiting on the first
+    // conflict: a sibling refresh worker holds it only briefly (~one embed), so a
+    // few retries pick up the queued ids in this run instead of stranding them
+    // until the next mutation. If a long `pm reindex` keeps it, we give up — that
+    // full pass re-embeds everything anyway and the next dispatch retries.
+    let release = null;
+    for (let attempt = 0; attempt < LOCK_ACQUIRE_ATTEMPTS && !release; attempt += 1) {
+        try {
+            release = await acquireLock(pmRoot, REINDEX_LOCK_ID, settings.locks.ttl_seconds, process.env.PM_AUTHOR ?? "pm-search-refresh", false, settings.governance.force_required_for_stale_lock);
+        }
+        catch {
+            if (attempt < LOCK_ACQUIRE_ATTEMPTS - 1) {
+                await delay(LOCK_ACQUIRE_BACKOFF_MS);
+            }
+        }
+    }
+    if (!release) {
+        return { processed, rounds: 0, warnings };
+    }
+    let rounds = 0;
+    let failed = false;
+    try {
+        for (;;) {
+            const ids = await drainPendingRefreshIds(pmRoot);
+            if (ids.length === 0) {
+                break;
+            }
+            rounds += 1;
+            try {
+                const result = await refresh(pmRoot, ids);
+                processed.push(...result.refreshed);
+                warnings.push(...result.warnings);
+            }
+            catch (error) {
+                warnings.push(`search_background_refresh_failed:${toErrorMessage(error)}`);
+                // Re-enqueue so the work is retried by a later dispatch rather than lost.
+                await enqueuePendingRefreshIds(pmRoot, ids);
+                failed = true;
+                break;
+            }
+        }
+    }
+    finally {
+        await release?.();
+    }
+    // Close the race where a sibling enqueued ids between our last empty drain and
+    // releasing the lock: re-dispatch so those ids are eventually processed. Skip
+    // this after a refresh failure — the failed ids were re-enqueued and an
+    // immediate respawn would just fail again, spinning indefinitely. They wait
+    // for the next mutation's dispatch instead.
+    const remaining = failed ? [] : await readPendingQueueIds(pmRoot);
+    if (remaining.length > 0) {
+        dispatchRefreshChild(pmRoot);
+    }
+    return { processed: [...new Set(processed)].sort((a, b) => a.localeCompare(b)), rounds, warnings };
+}
+// Expose internals for focused tests without widening the production surface
+// used by the mutation hot path.
+export const _backgroundRefreshInternals = {
+    pendingQueuePath,
+    acquireQueueGate,
+    releaseQueueGate,
+};
+//# sourceMappingURL=background-refresh.js.map
+//# debugId=d8990236-9b78-570d-bafa-5da0ce621293

package/dist/core/search/background-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-refresh.js","sources":["core/search/background-refresh.ts"],"sourceRoot":"/","sourcesContent":["import { spawn } from \"node:child_process\";\nimport { mkdirSync, rmSync, statSync } from \"node:fs\";\nimport path from \"node:path\";\n\nimport { pathExists, readFileIfExists, writeFileAtomic } from \"../fs/fs-utils.js\";\nimport { acquireLock } from \"../lock/lock.js\";\nimport { resolvePmPackageRootFromModule } from \"../packages/root.js\";\nimport { readSettings } from \"../store/settings.js\";\nimport { toErrorMessage } from \"../shared/primitives.js\";\nimport { resolveSettingsWithSemanticRuntimeDefaults } from \"./semantic-defaults.js\";\n\n/**\n * Shared lock id for any process that rewrites the local vector store. Reindex\n * and the background mutation-refresh worker both acquire this so they never\n * write concurrently and corrupt the store. Exported so `pm reindex` reuses the\n * same id rather than duplicating the literal.\n */\nexport const REINDEX_LOCK_ID = \"reindex\";\n\nconst PENDING_QUEUE_REL_PATH = \"search/pending-refresh.json\";\nconst PENDING_QUEUE_GATE_REL_PATH = \"search/pending-refresh.gate.lock\";\nconst PENDING_QUEUE_GATE_STALE_MS = 30_000;\n\n// Bounded reindex-lock retry for the background worker (~3.2s worst case).\nconst LOCK_ACQUIRE_ATTEMPTS = 8;\nconst LOCK_ACQUIRE_BACKOFF_MS = 400;\n\nconst SEARCH_REFRESH_INLINE_ENV = \"PM_SEARCH_REFRESH_INLINE\";\nconst SEARCH_REFRESH_CHILD_ENV = \"PM_SEARCH_REFRESH_CHILD\";\n\nfunction parseBooleanTrueLike(value: string | undefined): boolean {\n  if (typeof value !== \"string\") {\n    return false;\n  }\n  const normalized = value.trim().toLowerCase();\n  return normalized === \"1\" || normalized === \"true\" || normalized === \"yes\" || normalized === \"on\";\n}\n\n/**\n * Mutation search refresh runs inline (blocking) under test runners, inside the\n * background worker child itself, or when explicitly requested. Otherwise the\n * semantic refresh is dispatched to a detached child so mutations return without\n * waiting on embeddings. Mirrors the telemetry-flush inline gate so the full test\n * suite stays deterministic.\n */\nexport function shouldRunSearchRefreshInForeground(): boolean {\n  if (parseBooleanTrueLike(process.env[SEARCH_REFRESH_INLINE_ENV])) {\n    return true;\n  }\n  if (parseBooleanTrueLike(process.env[SEARCH_REFRESH_CHILD_ENV])) {\n    return true;\n  }\n  const nodeEnv = (process.env.NODE_ENV ?? \"\").trim().toLowerCase();\n  return (\n    typeof process.env.VITEST === \"string\" ||\n    typeof process.env.VITEST_WORKER_ID === \"string\" ||\n    nodeEnv === \"test\"\n  );\n}\n\nfunction pendingQueuePath(pmRoot: string): string {\n  return path.join(pmRoot, PENDING_QUEUE_REL_PATH);\n}\n\nfunction pendingQueueGatePath(pmRoot: string): string {\n  return path.join(pmRoot, PENDING_QUEUE_GATE_REL_PATH);\n}\n\nfunction acquireQueueGate(pmRoot: string): boolean {\n  const gatePath = pendingQueueGatePath(pmRoot);\n  try {\n    if (Date.now() - statSync(gatePath).mtimeMs < PENDING_QUEUE_GATE_STALE_MS) {\n      return false;\n    }\n    rmSync(gatePath, { recursive: true, force: true });\n  } catch {\n    // Missing gate is the common case; fall through to create it.\n  }\n  try {\n    mkdirSync(path.dirname(gatePath), { recursive: true });\n    mkdirSync(gatePath);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction releaseQueueGate(pmRoot: string): void {\n  try {\n    rmSync(pendingQueueGatePath(pmRoot), { recursive: true, force: true });\n  } catch {\n    // Best effort; a stale gate self-heals after PENDING_QUEUE_GATE_STALE_MS.\n  }\n}\n\nasync function withQueueGate<T>(pmRoot: string, fn: () => Promise<T>, fallback: T): Promise<T> {\n  // Briefly serialize read-modify-write access to the pending queue across the\n  // mutation process and the worker child. Acquisition is best effort; if a\n  // healthy gate is held we skip rather than risk a torn queue.\n  for (let attempt = 0; attempt < 50; attempt += 1) {\n    if (acquireQueueGate(pmRoot)) {\n      try {\n        return await fn();\n      } finally {\n        releaseQueueGate(pmRoot);\n      }\n    }\n    await delay(20);\n  }\n  return fallback;\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => {\n    setTimeout(resolve, ms).unref?.();\n  });\n}\n\nasync function readPendingQueueIds(pmRoot: string): Promise<string[]> {\n  const raw = await readFileIfExists(pendingQueuePath(pmRoot));\n  if (!raw || raw.trim().length === 0) {\n    return [];\n  }\n  try {\n    const parsed = JSON.parse(raw) as { ids?: unknown };\n    if (!Array.isArray(parsed.ids)) {\n      return [];\n    }\n    return parsed.ids.filter((id): id is string => typeof id === \"string\" && id.length > 0);\n  } catch {\n    return [];\n  }\n}\n\nasync function writePendingQueueIds(pmRoot: string, ids: string[]): Promise<void> {\n  await writeFileAtomic(pendingQueuePath(pmRoot), `${JSON.stringify({ ids })}\\n`);\n}\n\n/** Merge mutated item ids into the persistent pending-refresh queue. */\nexport async function enqueuePendingRefreshIds(pmRoot: string, itemIds: string[]): Promise<void> {\n  const incoming = itemIds.filter((id) => typeof id === \"string\" && id.trim().length > 0);\n  if (incoming.length === 0) {\n    return;\n  }\n  const mergeIncoming = async (): Promise<void> => {\n    const existing = await readPendingQueueIds(pmRoot);\n    const merged = [...new Set([...existing, ...incoming])].sort((left, right) => left.localeCompare(right));\n    await writePendingQueueIds(pmRoot, merged);\n  };\n  const gated = await withQueueGate(\n    pmRoot,\n    async () => {\n      await mergeIncoming();\n      return true;\n    },\n    false,\n  );\n  if (!gated) {\n    // The gate stayed contended past the retry budget. Never silently drop a\n    // mutation's refresh work: fall back to a best-effort unguarded merge.\n    // writeFileAtomic keeps the file valid; the only risk is losing a concurrent\n    // writer's delta, which its own next dispatch and the vector_index_stale\n    // warning both recover.\n    await mergeIncoming();\n  }\n}\n\n/** Atomically read and clear the pending-refresh queue, returning drained ids. */\nexport async function drainPendingRefreshIds(pmRoot: string): Promise<string[]> {\n  return withQueueGate(\n    pmRoot,\n    async () => {\n      const ids = await readPendingQueueIds(pmRoot);\n      if (ids.length > 0) {\n        await writePendingQueueIds(pmRoot, []);\n      }\n      return ids;\n    },\n    [],\n  );\n}\n\nfunction searchRefreshRunnerPath(): string {\n  return path.join(\n    resolvePmPackageRootFromModule(import.meta.url, [\"../../..\"]),\n    \"dist\",\n    \"cli\",\n    \"search-refresh.js\",\n  );\n}\n\n/**\n * Spawn the detached refresh worker child for this pm root. Best effort: a\n * failed dispatch must never keep the CLI alive or fail a mutation; the next\n * mutation re-dispatches and `vector_index_stale` warns about the catch-up\n * window in the meantime.\n */\nfunction dispatchRefreshChild(pmRoot: string): void {\n  try {\n    const child = spawn(process.execPath, [searchRefreshRunnerPath()], {\n      detached: true,\n      stdio: \"ignore\",\n      env: {\n        ...process.env,\n        PM_PATH: pmRoot,\n        [SEARCH_REFRESH_CHILD_ENV]: \"1\",\n      },\n    });\n    // A detached child can emit an async 'error' event (e.g. spawn EAGAIN/ENOENT,\n    // resource limits). Swallow it so it never becomes an unhandled error that\n    // crashes the parent CLI; dispatch is best effort.\n    child.on(\"error\", () => {});\n    child.unref();\n  } catch {\n    // Best effort — see doc comment above.\n  }\n}\n\n/**\n * Enqueue mutated ids and dispatch a detached worker child to refresh semantic\n * embeddings without blocking the mutation. The reindex lock the worker acquires\n * serializes concurrent refreshes, so the spawn itself stays unconditional and\n * cheap; a worker that loses the lock exits and its ids are drained by the holder.\n */\nexport async function scheduleBackgroundSemanticRefresh(pmRoot: string, itemIds: string[]): Promise<void> {\n  await enqueuePendingRefreshIds(pmRoot, itemIds);\n  dispatchRefreshChild(pmRoot);\n}\n\nexport interface SemanticRefreshWorkerResult {\n  processed: string[];\n  rounds: number;\n  warnings: string[];\n}\n\ntype SemanticRefreshFn = (\n  pmRoot: string,\n  itemIds: string[],\n) => Promise<{ refreshed: string[]; skipped: string[]; warnings: string[] }>;\n\n/**\n * Drain the pending queue and refresh semantic vectors under the reindex lock so\n * the local vector store is never rewritten concurrently. If the lock is held by\n * another worker we exit immediately — that holder drains our enqueued ids. After\n * releasing we re-check the queue once and re-dispatch if a sibling enqueued ids\n * during our final window, guaranteeing eventual processing.\n */\nexport async function runSemanticRefreshWorker(\n  pmRoot: string,\n  refresh: SemanticRefreshFn,\n): Promise<SemanticRefreshWorkerResult> {\n  const warnings: string[] = [];\n  const processed: string[] = [];\n  if (!(await pathExists(pmRoot))) {\n    return { processed, rounds: 0, warnings };\n  }\n\n  let settings: Awaited<ReturnType<typeof readSettings>>;\n  try {\n    settings = resolveSettingsWithSemanticRuntimeDefaults(await readSettings(pmRoot)).settings;\n  } catch (error: unknown) {\n    return { processed, rounds: 0, warnings: [`search_background_refresh_settings_read_failed:${toErrorMessage(error)}`] };\n  }\n\n  // Retry the reindex lock with backoff rather than exiting on the first\n  // conflict: a sibling refresh worker holds it only briefly (~one embed), so a\n  // few retries pick up the queued ids in this run instead of stranding them\n  // until the next mutation. If a long `pm reindex` keeps it, we give up — that\n  // full pass re-embeds everything anyway and the next dispatch retries.\n  let release: (() => Promise<void>) | null = null;\n  for (let attempt = 0; attempt < LOCK_ACQUIRE_ATTEMPTS && !release; attempt += 1) {\n    try {\n      release = await acquireLock(\n        pmRoot,\n        REINDEX_LOCK_ID,\n        settings.locks.ttl_seconds,\n        process.env.PM_AUTHOR ?? \"pm-search-refresh\",\n        false,\n        settings.governance.force_required_for_stale_lock,\n      );\n    } catch {\n      if (attempt < LOCK_ACQUIRE_ATTEMPTS - 1) {\n        await delay(LOCK_ACQUIRE_BACKOFF_MS);\n      }\n    }\n  }\n  if (!release) {\n    return { processed, rounds: 0, warnings };\n  }\n\n  let rounds = 0;\n  let failed = false;\n  try {\n    for (;;) {\n      const ids = await drainPendingRefreshIds(pmRoot);\n      if (ids.length === 0) {\n        break;\n      }\n      rounds += 1;\n      try {\n        const result = await refresh(pmRoot, ids);\n        processed.push(...result.refreshed);\n        warnings.push(...result.warnings);\n      } catch (error: unknown) {\n        warnings.push(`search_background_refresh_failed:${toErrorMessage(error)}`);\n        // Re-enqueue so the work is retried by a later dispatch rather than lost.\n        await enqueuePendingRefreshIds(pmRoot, ids);\n        failed = true;\n        break;\n      }\n    }\n  } finally {\n    await release?.();\n  }\n\n  // Close the race where a sibling enqueued ids between our last empty drain and\n  // releasing the lock: re-dispatch so those ids are eventually processed. Skip\n  // this after a refresh failure — the failed ids were re-enqueued and an\n  // immediate respawn would just fail again, spinning indefinitely. They wait\n  // for the next mutation's dispatch instead.\n  const remaining = failed ? [] : await readPendingQueueIds(pmRoot);\n  if (remaining.length > 0) {\n    dispatchRefreshChild(pmRoot);\n  }\n\n  return { processed: [...new Set(processed)].sort((a, b) => a.localeCompare(b)), rounds, warnings };\n}\n\n// Expose internals for focused tests without widening the production surface\n// used by the mutation hot path.\nexport const _backgroundRefreshInternals = {\n  pendingQueuePath,\n  acquireQueueGate,\n  releaseQueueGate,\n};\n"],"names":[],"mappings":"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","debugId":"d8990236-9b78-570d-bafa-5da0ce621293"}

package/dist/core/search/cache.d.ts

@@ -13,6 +13,17 @@ export interface SemanticMutationRefreshResult {
 export interface SearchMutationArtifactRefreshResult extends SearchCacheInvalidationResult {
     refreshed: string[];
     skipped: string[];
+    /** True when the semantic refresh was dispatched to a detached background worker. */
+    scheduled?: boolean;
+}
+export interface RefreshSearchArtifactsForMutationOptions {
+    /**
+     * When true and semantic search is active, the (slow) embedding refresh is
+     * dispatched to a detached background worker instead of awaited inline so the
+     * mutation returns immediately. The synchronous keyword-cache invalidation
+     * still runs first. Callers pass this only outside test runners.
+     */
+    background?: boolean;
 }
 export interface SemanticRefreshOptions {
     settings?: Awaited<ReturnType<typeof readSettings>>;
@@ -26,4 +37,12 @@ export declare function readVectorizationStatusLedger(pmRoot: string): Promise<V
 export declare function writeVectorizationStatusLedger(pmRoot: string, entries: Record<string, string>): Promise<void>;
 export declare function invalidateSearchCacheArtifacts(pmRoot: string): Promise<SearchCacheInvalidationResult>;
 export declare function refreshSemanticEmbeddingsForMutatedItems(pmRoot: string, itemIds: string[], options?: SemanticRefreshOptions): Promise<SemanticMutationRefreshResult>;
-export declare function refreshSearchArtifactsForMutation(pmRoot: string, itemIds: string[]): Promise<SearchMutationArtifactRefreshResult>;
+/**
+ * Returns true when a semantic embedding refresh would do real work for these
+ * settings (an embedding provider AND a vector store both resolve). Used to
+ * decide whether a mutation's refresh is worth dispatching to a background
+ * worker — when semantic search is not configured the inline path is already a
+ * fast no-op and no child is spawned.
+ */
+export declare function isSemanticRefreshActive(settings: Awaited<ReturnType<typeof readSettings>>, applyRuntimeDefaults: boolean): boolean;
+export declare function refreshSearchArtifactsForMutation(pmRoot: string, itemIds: string[], options?: RefreshSearchArtifactsForMutationOptions): Promise<SearchMutationArtifactRefreshResult>;

package/dist/core/search/cache.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="85a2e33b-e20c-5ad4-b9fe-e54951dc49a3")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d04073fd-fa5a-5454-8e71-11bc477005b0")}catch(e){}}();
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../extensions/index.js";
 import { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
@@ -12,6 +12,7 @@ import { executeEmbeddingBatchesWithRetry } from "./embedding-batches.js";
 import { buildSemanticCorpusInput } from "./corpus.js";
 import { resolveEmbeddingProviders } from "./providers.js";
 import { resolveSettingsWithSemanticRuntimeDefaults } from "./semantic-defaults.js";
+import { scheduleBackgroundSemanticRefresh } from "./background-refresh.js";
 import { executeVectorDelete, executeVectorUpsert, resolveVectorStores } from "./vector-stores.js";
 import { nowIso } from "../shared/time.js";
 export const SEARCH_CACHE_ARTIFACT_PATHS = ["index/manifest.json", "search/embeddings.jsonl"];
@@ -290,10 +291,80 @@ export async function refreshSemanticEmbeddingsForMutatedItems(pmRoot, itemIds,
         warnings: [...workload.warnings, ...refreshedResult.warnings, ...pruneResult.warnings, ...ledgerWarnings],
     };
 }
-export async function refreshSearchArtifactsForMutation(pmRoot, itemIds) {
+/**
+ * Returns true when a semantic embedding refresh would do real work for these
+ * settings (an embedding provider AND a vector store both resolve). Used to
+ * decide whether a mutation's refresh is worth dispatching to a background
+ * worker — when semantic search is not configured the inline path is already a
+ * fast no-op and no child is spawned.
+ */
+export function isSemanticRefreshActive(settings, applyRuntimeDefaults) {
+    const effectiveSettings = applyRuntimeDefaults
+        ? resolveSettingsWithSemanticRuntimeDefaults(settings).settings
+        : settings;
+    return Boolean(resolveEmbeddingProviders(effectiveSettings).active && resolveVectorStores(effectiveSettings).active);
+}
+export async function refreshSearchArtifactsForMutation(pmRoot, itemIds, options = {}) {
     const invalidation = await invalidateSearchCacheArtifacts(pmRoot);
-    const semanticRefresh = await refreshSemanticEmbeddingsForMutatedItems(pmRoot, itemIds, {
-        apply_runtime_defaults: true,
+    const normalizedItemIds = toUniqueSorted(itemIds);
+    if (normalizedItemIds.length === 0) {
+        return {
+            invalidated: invalidation.invalidated,
+            refreshed: [],
+            skipped: [],
+            warnings: invalidation.warnings,
+        };
+    }
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        const semanticRefresh = await refreshSemanticEmbeddingsForMutatedItems(pmRoot, normalizedItemIds);
+        return {
+            invalidated: invalidation.invalidated,
+            refreshed: semanticRefresh.refreshed,
+            skipped: semanticRefresh.skipped,
+            warnings: [...invalidation.warnings, ...semanticRefresh.warnings],
+        };
+    }
+    let settings;
+    try {
+        settings = await readSettings(pmRoot);
+    }
+    catch (error) {
+        return {
+            invalidated: invalidation.invalidated,
+            refreshed: [],
+            skipped: normalizedItemIds,
+            warnings: [
+                ...invalidation.warnings,
+                `search_semantic_refresh_skipped:settings_read_failed:${toErrorMessage(error)}`,
+            ],
+        };
+    }
+    if (settings.search.mutation_refresh_policy === "cache_only") {
+        return {
+            invalidated: invalidation.invalidated,
+            refreshed: [],
+            skipped: normalizedItemIds,
+            warnings: invalidation.warnings,
+        };
+    }
+    const applyRuntimeDefaults = settings.search.mutation_refresh_policy === "semantic_auto";
+    // Keyword cache is already invalidated synchronously above (so keyword search
+    // stays immediately correct). When requested, dispatch the slow embedding
+    // refresh to a detached worker so the mutation returns instantly; the
+    // vector_index_stale health/search warning covers the catch-up window.
+    if (options.background && isSemanticRefreshActive(settings, applyRuntimeDefaults)) {
+        await scheduleBackgroundSemanticRefresh(pmRoot, normalizedItemIds);
+        return {
+            invalidated: invalidation.invalidated,
+            refreshed: [],
+            skipped: [],
+            warnings: [...invalidation.warnings, "search_semantic_refresh_scheduled_background"],
+            scheduled: true,
+        };
+    }
+    const semanticRefresh = await refreshSemanticEmbeddingsForMutatedItems(pmRoot, normalizedItemIds, {
+        settings,
+        apply_runtime_defaults: applyRuntimeDefaults,
     });
     return {
         invalidated: invalidation.invalidated,
@@ -303,4 +374,4 @@ export async function refreshSearchArtifactsForMutation(pmRoot, itemIds) {
     };
 }
 //# sourceMappingURL=cache.js.map
-//# debugId=85a2e33b-e20c-5ad4-b9fe-e54951dc49a3
+//# debugId=d04073fd-fa5a-5454-8e71-11bc477005b0