recallnest 3.0.0 → 4.0.0

package/src/distill-lock.ts

@@ -1,9 +1,23 @@
 /**
- * CC-6: Distill gate — PID-based lock file + session gate.
- * Lock file mtime serves as lastDistillAt timestamp (no separate field).
+ * CC-6: Distill gate + P0-1 named cross-process locks.
  *
- * - acquireLock(): write current PID, check existing lock PID liveness + mtime expiry
- * - releaseLock(): delete lock file (mtime naturally updates to now on success)
+ * Mutual exclusion is a kernel advisory lock: flock(2) on a descriptor that stays open for as long
+ * as the lock is held (src/flock.ts). The kernel drops it when the holder closes the descriptor,
+ * exits, or is SIGKILLed, so there is no stale-lock reclaim, no PID or expiry check deciding that a
+ * live holder may be pushed out, no marker files and no heartbeat. The lock file still carries
+ * `<pid>:<token>:flock:<acquiredAtMs>:<maxHoldMs>` for diagnostics (inspectLock, timeout messages,
+ * the stuck-holder warning); nothing decides ownership from its content.
+ *
+ * ROLLOUT — the previous versions of this file (PID + mtime in the lock file, reclaimed by
+ * unlink-and-recreate) do not take the flock, so old and new processes do not exclude each other.
+ * Upgrade by stopping EVERY RecallNest process that shares the data directory (all mcp-server
+ * instances, the HTTP API, launchd jobs: incremental-ingest, dream, gc, memory-reconcile, …), then
+ * starting the new ones. As a guard for a missed old process: a lock file in the old format whose
+ * PID is alive is treated as held and is never taken over (see acquireLock); if it was left by a
+ * process that is gone and its PID has been reused, a warning names the file to delete.
+ *
+ * - acquireLock(): open + non-blocking flock, write the diagnostic body
+ * - releaseLock(): unlink (while still locked) + close; never touches a lock this process does not hold
  * - rollbackLock(previousMtime): on failure, rewind lock mtime so next run retries
  * - shouldDistill(checkpointCount): session gate — checkpoint count < 3 → skip
  * - getLastDistillTime(): read lock file mtime, return 0 if absent
@@ -17,10 +31,16 @@ import {
   statSync,
   utimesSync,
   existsSync,
+  fstatSync,
+  closeSync,
+  ftruncateSync,
+  writeSync,
 } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { join, dirname } from "node:path";
 import * as envConfig from "./env-config.js";
+import { openLockFile, tryLockExclusive, unlockFd } from "./flock.js";
+import { logWarn } from "./stderr-log.js";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -29,7 +49,11 @@ import * as envConfig from "./env-config.js";
 export interface DistillLockConfig {
   /** Path to the lock file (default: data/distill.lock) */
   lockPath: string;
-  /** Lock expiry in ms (default: 3600000 = 1h) */
+  /**
+   * How long this holder expects to keep the lock (default: 3600000 = 1h). Recorded in the lock
+   * file; holding it longer only raises the stuck-holder warning. It never lets another process
+   * take the lock: only the kernel releases a flock.
+   */
   expireMs: number;
   /** Minimum checkpoint count before distill is allowed (default: 3) */
   minCheckpoints: number;
@@ -58,96 +82,174 @@ function isPidAlive(pid: number): boolean {
   }
 }
 
-// P2: in-process record of the ownership token we wrote into each lock file we hold.
-// releaseLock only removes a lock whose on-disk token still matches — so if our lock
-// expired mid-run and another process legitimately reclaimed it, our finally-release
-// won't delete the new owner's lock (which would break mutual exclusion).
-const heldTokens = new Map<string, string>();
-
-/** Parse the PID prefix from a lock file body (`<pid>` legacy or `<pid>:<token>`). */
+/** Parse the PID prefix from a lock file body (`<pid>` legacy, `<pid>:<token>…`). */
 function parsePid(content: string): number {
   return parseInt((content.split(":")[0] ?? "").trim(), 10);
 }
 
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
+const FLOCK_TAG = "flock";
 
-/**
- * Try to acquire the distill lock.
- * Returns true if lock was acquired, false if another live process holds it.
- */
-export function acquireLock(cfg?: Partial<DistillLockConfig>): boolean {
-  const { lockPath, expireMs } = resolveConfig(cfg);
-  mkdirSync(dirname(lockPath), { recursive: true });
+/** What this process holds: the open, flocked descriptor, its inode, and the body we wrote. */
+interface HeldLock {
+  fd: number;
+  dev: number;
+  ino: number;
+  body: string;
+}
+
+// Locks held by this process, by path. releaseLock only acts on an entry here, so a release can
+// never remove a lock some other process (or another call in this process) holds.
+const heldLocks = new Map<string, HeldLock>();
+
+interface HolderInfo {
+  pid: number;
+  token: string;
+  acquiredAt: number;
+  maxHoldMs: number;
+}
+
+/** Parse a body written by this version; null for the legacy format or garbage. */
+function parseFlockBody(content: string): HolderInfo | null {
+  const [pid, token, tag, acquiredAt, maxHoldMs] = content.trim().split(":");
+  if (tag !== FLOCK_TAG || pid === undefined || token === undefined) return null;
+  const info = { pid: parseInt(pid, 10), token, acquiredAt: Number(acquiredAt), maxHoldMs: Number(maxHoldMs) };
+  return Number.isNaN(info.pid) || Number.isNaN(info.acquiredAt) || Number.isNaN(info.maxHoldMs) ? null : info;
+}
 
-  // Fast path: atomic exclusive create. On POSIX the O_EXCL ("wx") open wins the
-  // cross-process race — only one of N processes creating the same lock succeeds.
-  // This closes the check-then-write TOCTOU the previous existsSync+writeFileSync
-  // form had (two processes could both see "no lock" then both write); the P0-1
-  // store-write lock relies on acquisition being truly exclusive.
-  if (tryExclusiveCreate(lockPath)) return true;
+const warnedOnce = new Set<string>();
 
-  // Lock file exists — decide whether it is reclaimable (dead holder or expired).
-  let existingPid = NaN;
-  let mtime = 0;
+function warnOnce(key: string, message: string): void {
+  if (warnedOnce.has(key)) return;
+  warnedOnce.add(key);
+  logWarn(message);
+}
+
+/**
+ * A body from a pre-flock version naming a live PID. Such a process does not take the flock, so
+ * holding the flock proves nothing about it: refuse rather than take a lock it may be inside.
+ */
+function heldByLegacyProcess(lockPath: string, content: string, expectedHoldMs: number): boolean {
+  if (content.trim() === "" || parseFlockBody(content) !== null) return false;
+  const pid = parsePid(content);
+  if (isNaN(pid) || !isPidAlive(pid)) return false;
+  let ageMs = 0;
   try {
-    existingPid = parsePid(readFileSync(lockPath, "utf-8"));
-    mtime = statSync(lockPath).mtimeMs;
+    ageMs = Date.now() - statSync(lockPath).mtimeMs;
   } catch {
-    // Holder released between our failed create and this read — retry the create.
-    return tryExclusiveCreate(lockPath);
+    /* gone: report age 0 */
   }
-  const expired = Date.now() - mtime > expireMs;
-  if (!isNaN(existingPid) && isPidAlive(existingPid) && !expired) {
-    return false; // held by a live process, not expired
+  if (ageMs > expectedHoldMs) {
+    warnOnce(`legacy|${lockPath}|${content}`,
+      `[distill-lock] ${lockPath} is in the pre-flock format and names live pid ${pid} ` +
+      `(${Math.round(ageMs / 1000)} s old); treating it as held. If no RecallNest process from ` +
+      `before the flock upgrade is still running, that pid has been reused: delete the file.`);
   }
+  return true;
+}
 
-  // Reclaim a stale lock: remove it, then re-create atomically. If a competing
-  // process reclaims first, our O_EXCL create fails and we concede the race.
+/** "pid 123, held 45 s (max hold 30 s)" for messages; null when the file says nothing useful. */
+function describeHolder(lockPath: string): string | null {
+  let content: string;
   try {
-    unlinkSync(lockPath);
+    content = readFileSync(lockPath, "utf-8");
   } catch {
-    /* already gone — fall through to the atomic create */
+    return null;
+  }
+  const info = parseFlockBody(content);
+  if (info === null) {
+    const pid = parsePid(content);
+    return isNaN(pid) ? null : `pid ${pid} (pre-flock lock file)`;
   }
-  return tryExclusiveCreate(lockPath);
+  const heldMs = Date.now() - info.acquiredAt;
+  return `pid ${info.pid}, held ${Math.round(heldMs / 1000)} s (max hold ${Math.round(info.maxHoldMs / 1000)} s)`;
 }
 
 /**
- * Atomic O_EXCL create of the lock file. Writes a unique ownership token (`<pid>:<uuid>`)
- * and records it so releaseLock can verify we still own the lock. false on EEXIST.
+ * Waiter-side stuck-holder warning: the holder's own watchdog cannot fire if its event loop is
+ * blocked, so whoever is waiting also says so, once per holder.
  */
-function tryExclusiveCreate(lockPath: string): boolean {
-  const token = `${process.pid}:${randomUUID()}`;
+function warnIfHolderOverdue(key: string, lockPath: string): void {
+  let content: string;
   try {
-    writeFileSync(lockPath, token, { encoding: "utf-8", flag: "wx" });
-    heldTokens.set(lockPath, token);
-    return true;
-  } catch (err) {
-    if ((err as { code?: unknown }).code === "EEXIST") return false;
-    throw err;
+    content = readFileSync(lockPath, "utf-8");
+  } catch {
+    return;
   }
+  const info = parseFlockBody(content);
+  if (info === null) return;
+  const heldMs = Date.now() - info.acquiredAt;
+  if (heldMs <= info.maxHoldMs) return;
+  warnOnce(`overdue|${lockPath}|${info.token}`,
+    `[distill-lock] lock '${key}' has been held by pid ${info.pid} for ${Math.round(heldMs / 1000)} s, ` +
+    `past its max hold of ${Math.round(info.maxHoldMs / 1000)} s. Writers waiting on it will time out ` +
+    `until that process finishes or is restarted.`);
 }
 
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
 /**
- * Release the distill lock. If we hold a known ownership token for this path, only
- * remove the file when its on-disk token still matches ours — otherwise our lock was
- * expired and reclaimed by another process, and deleting would evict the new owner.
- * When we hold no token (e.g. a direct caller/test-written lock) fall back to removing.
+ * Try to acquire the lock without waiting.
+ * Returns true if acquired, false if another holder (another process, or another call in this
+ * process) has it, or if a live pre-flock process is named in the lock file.
  */
-export function releaseLock(cfg?: Partial<DistillLockConfig>): void {
-  const { lockPath } = resolveConfig(cfg);
-  const ourToken = heldTokens.get(lockPath);
-  heldTokens.delete(lockPath);
-  if (!existsSync(lockPath)) return;
-  if (ourToken !== undefined) {
+export function acquireLock(cfg?: Partial<DistillLockConfig>): boolean {
+  const { lockPath, expireMs } = resolveConfig(cfg);
+  if (heldLocks.has(lockPath)) return false;
+  mkdirSync(dirname(lockPath), { recursive: true });
+
+  // A releaser unlinks the file while it still holds the flock; a process that opened the path
+  // before that unlink can get the flock on the orphaned inode afterwards. So after locking,
+  // check that the path still names our inode, and start over if not.
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const fd = openLockFile(lockPath);
+    let keep = false;
     try {
-      if (readFileSync(lockPath, "utf-8").trim() !== ourToken) return; // reclaimed by another owner
-    } catch {
-      return;
+      if (!tryLockExclusive(fd)) return false;
+      const ours = fstatSync(fd);
+      let onDisk: ReturnType<typeof statSync>;
+      try {
+        onDisk = statSync(lockPath);
+      } catch {
+        continue; // unlinked after we opened it
+      }
+      if (onDisk.ino !== ours.ino || onDisk.dev !== ours.dev) continue;
+
+      if (heldByLegacyProcess(lockPath, readFileSync(fd, "utf-8"), expireMs)) return false;
+
+      const body = `${process.pid}:${randomUUID()}:${FLOCK_TAG}:${Date.now()}:${expireMs}`;
+      ftruncateSync(fd, 0);
+      writeSync(fd, body, 0);
+      heldLocks.set(lockPath, { fd, dev: ours.dev, ino: ours.ino, body });
+      keep = true;
+      return true;
+    } finally {
+      if (!keep) closeSync(fd);
     }
   }
-  unlinkSync(lockPath);
+  return false;
+}
+
+/**
+ * Release a lock this process holds: remove the file while still holding the flock (so a waiter
+ * that opened it earlier sees the inode is gone and retries), then close the descriptor, which
+ * drops the flock. A lock this process does not hold is left alone — never unlinked blind.
+ */
+export function releaseLock(cfg?: Partial<DistillLockConfig>): void {
+  const { lockPath } = resolveConfig(cfg);
+  const held = heldLocks.get(lockPath);
+  if (held === undefined) return;
+  heldLocks.delete(lockPath);
+  try {
+    const onDisk = statSync(lockPath);
+    if (onDisk.ino === held.ino && onDisk.dev === held.dev) unlinkSync(lockPath);
+  } catch {
+    /* already gone */
+  } finally {
+    unlockFd(held.fd);
+    closeSync(held.fd);
+  }
 }
 
 /**
@@ -194,6 +296,21 @@ export function locksDir(lockDir?: string): string {
   return lockDir ?? join(envConfig.dataDir(), "locks");
 }
 
+/**
+ * 只读查看一把命名锁：在不在、持有者进程活没活、锁文件多久没更新。不改任何东西。
+ * 记忆文件对账用它区分「dream / GC 正常在跑」和「某个进程占着锁很久没动静」（后者要报警，不然对账会一直静默跳过）。
+ */
+export function inspectLock(key: string, lockDir?: string): { exists: boolean; pid: number | null; pidAlive: boolean; ageMs: number | null } {
+  const lockPath = lockPathForKey(key, lockDir);
+  try {
+    const pid = parsePid(readFileSync(lockPath, "utf-8"));
+    const ageMs = Date.now() - statSync(lockPath).mtimeMs;
+    return { exists: true, pid: isNaN(pid) ? null : pid, pidAlive: !isNaN(pid) && isPidAlive(pid), ageMs };
+  } catch {
+    return { exists: false, pid: null, pidAlive: false, ageMs: null };
+  }
+}
+
 /**
  * Resolve a lock key (e.g. "store-write", "dream-<scope>", "gc-global") to a safe
  * lock-file path. The key is sanitized for the filesystem and suffixed with a short
@@ -206,11 +323,17 @@ export function lockPathForKey(key: string, lockDir?: string): string {
 }
 
 export interface WithLockOptions {
-  /** Stale-lock reclaim window in ms (default 600_000 = 10min). */
+  /**
+   * How long this holder expects to keep the lock (default 600_000 = 10 min). Recorded in the lock
+   * file. Past it the holder logs a loud warning and `fn`'s AbortSignal fires; waiters log too.
+   * It never lets anyone take the lock away from a live holder.
+   */
+  maxHoldMs?: number;
+  /** Older name for maxHoldMs, kept so existing callers read the same; maxHoldMs wins if both are set. */
   expireMs?: number;
   /** Override the base lock directory (tests). */
   lockDir?: string;
-  /** Behavior when another live process holds the lock (default "skip"). */
+  /** Behavior when another holder has the lock (default "skip"). */
   onBusy?: "skip" | "wait";
   /** For onBusy="wait": total time budget before throwing (default 10_000). */
   waitTimeoutMs?: number;
@@ -222,21 +345,39 @@ export type WithLockOutcome<T> =
   | { ran: true; result: T }
   | { ran: false; reason: "locked_by_another_process" };
 
+/** Reason carried by the AbortSignal handed to `fn` once the lock is held past its max hold. */
+export class LockHoldDeadlineError extends Error {
+  constructor(readonly key: string, readonly maxHoldMs: number) {
+    super(`lock '${key}' held past its max hold of ${maxHoldMs} ms`);
+    this.name = "LockHoldDeadlineError";
+  }
+}
+
 const sleep = (ms: number): Promise<void> =>
   new Promise((resolve) => setTimeout(resolve, ms));
 
+/** setTimeout/setInterval treat longer delays as 1 ms; such a max hold means "no deadline". */
+const MAX_TIMER_MS = 2_147_483_647;
+
 /**
  * Run `fn` while holding a named cross-process lock, releasing it afterwards
  * (even on throw). Maintenance-type writes use onBusy:"skip" — for a personal
  * store, skipping a redundant dream/consolidate/gc run beats queueing it.
+ *
+ * Stuck holders: once `fn` has held the lock for `maxHoldMs`, this process logs a warning (and
+ * again every `maxHoldMs` while it still holds it) and aborts the signal passed to `fn`. The lock
+ * itself is NOT released then — `fn` may be in the middle of a write, and handing the lock to the
+ * next writer would be exactly the double-writer bug this lock exists to prevent. A caller that can
+ * stop at a safe point (e.g. between independent batches) checks `signal.aborted` and returns.
  */
 export async function withLock<T>(
   key: string,
-  fn: () => Promise<T>,
+  fn: (signal: AbortSignal) => Promise<T>,
   opts: WithLockOptions = {},
 ): Promise<WithLockOutcome<T>> {
   const lockPath = lockPathForKey(key, opts.lockDir);
-  const lockCfg = { lockPath, expireMs: opts.expireMs ?? 600_000 };
+  const maxHoldMs = opts.maxHoldMs ?? opts.expireMs ?? 600_000;
+  const lockCfg = { lockPath, expireMs: maxHoldMs };
 
   if (!acquireLock(lockCfg)) {
     if ((opts.onBusy ?? "skip") === "skip") {
@@ -248,6 +389,7 @@ export async function withLock<T>(
     const pollMs = opts.pollMs ?? 50;
     let acquired = false;
     while (Date.now() < deadline) {
+      warnIfHolderOverdue(key, lockPath);
       await sleep(pollMs);
       if (acquireLock(lockCfg)) {
         acquired = true;
@@ -255,13 +397,33 @@ export async function withLock<T>(
       }
     }
     if (!acquired) {
-      throw new Error(`lock '${key}' timed out after ${timeoutMs}ms (held by another process)`);
+      const holder = describeHolder(lockPath);
+      throw new Error(`lock '${key}' timed out after ${timeoutMs}ms (held by ${holder ?? "another process"})`);
     }
   }
 
+  const controller = new AbortController();
+  const acquiredAt = Date.now();
+  let repeat: ReturnType<typeof setInterval> | undefined;
+  const overdue = (): void => {
+    logWarn(`[distill-lock] lock '${key}' held by this process (pid ${process.pid}) for ` +
+      `${Math.round((Date.now() - acquiredAt) / 1000)} s, past its max hold of ${Math.round(maxHoldMs / 1000)} s. ` +
+      `Its critical section looks stuck; other writers time out until it finishes or this process is restarted.`);
+  };
+  const watchdog = maxHoldMs <= MAX_TIMER_MS
+    ? setTimeout(() => {
+      overdue();
+      controller.abort(new LockHoldDeadlineError(key, maxHoldMs));
+      repeat = setInterval(overdue, maxHoldMs);
+      repeat.unref?.();
+    }, maxHoldMs)
+    : undefined;
+  watchdog?.unref?.();
   try {
-    return { ran: true, result: await fn() };
+    return { ran: true, result: await fn(controller.signal) };
   } finally {
+    if (watchdog !== undefined) clearTimeout(watchdog);
+    if (repeat !== undefined) clearInterval(repeat);
     releaseLock(lockCfg);
   }
 }
@@ -274,7 +436,7 @@ export async function withLock<T>(
  */
 export async function withWriteLock<T>(
   key: string,
-  fn: () => Promise<T>,
+  fn: (signal: AbortSignal) => Promise<T>,
   opts: Omit<WithLockOptions, "onBusy"> = {},
 ): Promise<T> {
   const outcome = await withLock(key, fn, { ...opts, onBusy: "wait" });
@@ -299,3 +461,13 @@ export function stampLock(cfg?: Partial<DistillLockConfig>): void {
   // read back via getLastDistillTime.
   writeFileSync(lockPath, String(process.pid), "utf-8");
 }
+
+/** Remove a stamp written by stampLock (tests). Stamps are markers, not locks: nobody holds them. */
+export function clearStamp(cfg?: Partial<DistillLockConfig>): void {
+  const { lockPath } = resolveConfig(cfg);
+  try {
+    unlinkSync(lockPath);
+  } catch {
+    /* already gone */
+  }
+}

package/src/dream-pipeline.ts

@@ -98,7 +98,9 @@ export const DEFAULT_DREAM_CONFIG: DreamConfig = {
   maxEntriesPerRun: 500,
   autoRunBudgetMs: 2 * 60 * 60 * 1000,
   autoExcludeScopes: ["memory"],
-  neverDreamScopes: ["memory:pivot"],
+  // checkpoint（2026-10-07）：每场会话一行的 checkpoint 镜像（src/checkpoint-mirror.ts），只由镜像自己按会话覆盖；
+  // 合并它会把不同会话的状态揉成一条，或把正在被覆盖的行标成 superseded。
+  neverDreamScopes: ["memory:pivot", "checkpoint"],
   gc: DEFAULT_AUTO_GC_CONFIG,
 };
 

package/src/embedder.ts

@@ -103,6 +103,24 @@ export interface EmbeddingConfig {
   normalized?: boolean;
   /** Enable automatic chunking for documents exceeding context limits (default: true) */
   chunking?: boolean;
+
+  /**
+   * Per-request timeout (ms) handed to the OpenAI-compatible client.
+   *
+   * **Unset is the default and keeps the historical behavior**: no `timeout` key is
+   * passed to the SDK at all, so the client falls back to its own default (600s in
+   * openai v7). That default is deliberately left alone — bulk embedding of long
+   * documents is legitimately slow, and lowering it globally would turn working
+   * ingests into failures.
+   *
+   * Worth setting on latency-sensitive callers: the SDK default stacks with the SDK's
+   * own 2 retries *and* Embedder's 2 transient retries, so a black-holed endpoint can
+   * hold a single embed call for far longer than any caller expects.
+   *
+   * Non-finite or non-positive values are ignored (treated as unset) rather than
+   * throwing, matching how `env-config.ts` validates its other numeric knobs.
+   */
+  timeoutMs?: number;
 }
 
 // Known embedding model dimensions
@@ -205,9 +223,15 @@ export class Embedder {
     // Enable auto-chunking by default for better handling of long documents
     this._autoChunk = config.chunking !== false;
 
+    const timeoutMs =
+      typeof config.timeoutMs === "number" && Number.isFinite(config.timeoutMs) && config.timeoutMs > 0
+        ? config.timeoutMs
+        : undefined;
+
     this.client = new OpenAI({
       apiKey: resolvedApiKey,
       ...(config.baseURL ? { baseURL: config.baseURL } : {}),
+      ...(timeoutMs !== undefined ? { timeout: timeoutMs } : {}),
     });
 
     this.dimensions = getVectorDimensions(config.model, config.dimensions);

package/src/env-config.ts

@@ -39,6 +39,47 @@
 
 export const multiVector = (): boolean => process.env.RECALLNEST_MULTI_VECTOR === "true";
 
+// --- 写入时预演触发器（T-Mem 借鉴，2026-09-22）---
+// 默认开；显式 "false" 关。侧表 memory_triggers 不存在时 TriggerStore 自建，读路径失败一律 fail-open。
+export const triggerRecall = (): boolean => process.env.RECALLNEST_TRIGGER_RECALL !== "false";
+/**
+ * trigger 命中的余弦硬闸。T-Mem 论文默认 0.85 是他们的嵌入器；本库 jina-embeddings-v5-text-small
+ * query↔query 余弦压得很紧：2026-09-22 用 12 条 canary 校准——真联想命中 0.52–0.67、无关噪声最高 0.53，
+ * 0.50 让 canary-A-mem0-borrow 从 70% 掉到 40%，0.55 与接线前逐条一致。要换嵌入器先跑 `triggers-calibrate` 重定。
+ */
+export const triggerGate = (): number => {
+  const raw = Number(process.env.RECALLNEST_TRIGGER_GATE);
+  return Number.isFinite(raw) && raw > 0 && raw < 1 ? raw : 0.55;
+};
+/**
+ * 软闸：余弦没过硬闸、但 query 与 trigger 词面重合够高时也放行（trigger 是她自己的口语问法，
+ * 她将来的问法与预演的问法常常共用同几个字：榜 / 排名 / 清一清）。09-22 校准：真命中 overlap 0.20–0.64，
+ * 无关噪声 0–0.20，但关键词短 query 会被共用词撑高——所以再加一道 query 长度门槛（见下）；取余弦 ≥0.40 且 overlap ≥0.40。
+ */
+export const triggerSoftGate = (): number => {
+  const raw = Number(process.env.RECALLNEST_TRIGGER_SOFT_GATE);
+  return Number.isFinite(raw) && raw > 0 && raw < 1 ? raw : 0.40;
+};
+export const triggerMinOverlap = (): number => {
+  const raw = Number(process.env.RECALLNEST_TRIGGER_MIN_OVERLAP);
+  return Number.isFinite(raw) && raw > 0 && raw < 1 ? raw : 0.40;
+};
+/**
+ * 软闸只对「像一句话的问法」开：query 去停用词后至少这么多 token（CJK 按字）。
+ * 09-22 实测：「OpenClaw 记忆系统」(5 token) 与「taobao 这个 mcp 是官方的吗」(7 token) 这类关键词 query，
+ * 词面重合被一个共用词（记忆系统 / mcp）撑到 0.3–0.7，把同话题的旁支宿主顶到第一、二名，
+ * 20 条回归掉了两条；联想入口本来就是给「换个情境重提旧事」的整句问法用的，关键词 query 走向量 / BM25 就够。
+ */
+export const triggerSoftMinQueryTokens = (): number => {
+  const raw = Number(process.env.RECALLNEST_TRIGGER_SOFT_MIN_QUERY_TOKENS);
+  return Number.isFinite(raw) && raw >= 1 && raw <= 64 ? Math.floor(raw) : 8;
+};
+/** 每次检索最多让多少个宿主经 trigger 进入候选池。 */
+export const triggerTopK = (): number => {
+  const raw = Number(process.env.RECALLNEST_TRIGGER_TOP_K);
+  return Number.isFinite(raw) && raw >= 1 && raw <= 50 ? Math.floor(raw) : 10;
+};
+
 export const emotionScoring = (): boolean => process.env.RECALLNEST_EMOTION_SCORING === "true";
 
 export const predictiveMemory = (): boolean => process.env.RECALLNEST_PREDICTIVE_MEMORY === "true";
@@ -82,6 +123,71 @@ export const layerAdmissionMin = (): number => {
   return Number.isFinite(n) && n > 0 ? n : 3;
 };
 
+// --- 排序上把相关度与流行度拆开（2026-09-25，open-loops「RecallNest 检索评分链」症状 C）---
+
+/**
+ * 流行度信号怎么进排序：
+ *   bounded — 默认（2026-09-25 起，Alice 看过正式 shadow 后拍板切）：三环都不跑；链尾一步
+ *             score × (1 + popularityBonusMax · h)，h = min(1, log2(1+evolution.accessCount)/5)，
+ *             只加不减、这一环不截平（检索器内部按原值排序，retrieve() 出口才截到 1）；下游「给全文」档用 0.80
+ *   legacy  — 只在显式设 `legacy` 时走：切默认之前的行为逐字节不变（访问计数加成、热度混合、频次加成三环，各自截在 1.0）。
+ *             切回旧行为只要在 mcp.env 里加这一行。
+ */
+export const popularityRanking = (): "legacy" | "bounded" =>
+  process.env.RECALLNEST_POPULARITY_RANKING === "legacy" ? "legacy" : "bounded";
+
+/**
+ * trigger 那一路不做长度归一：以 trigger 分为底走一遍与正文相同的前置环节，长度归一后取两路较大。
+ * trigger 独自带入或主导的宿主两路相同，等于免长度归一。默认开（2026-09-25 起），只有显式设 `false` 才关，
+ * 同 RECALLNEST_TRIGGER_RECALL 的写法。
+ */
+export const triggerLengthExempt = (): boolean =>
+  process.env.RECALLNEST_TRIGGER_LENGTH_EXEMPT !== "false";
+
+/**
+ * 下游「给全文」那一档的分数线（adaptive 全文、resume_context 折叠视图 L2）。
+ * bounded 下热门条目不再被乘到 1.0，分数回到相关度的水平，0.85 那条线就太高了——
+ * 同一份快照上判过分档的前 5 条目里，正确答案拿全文的从 26 条掉到 18 条；0.80 是 32 条
+ * （第二步 plan §一.1，正式 shadow 用整组渲染回放复核）。legacy 下仍是 0.85。
+ */
+export const fullTextScoreThreshold = (): number =>
+  popularityRanking() === "bounded" ? 0.80 : 0.85;
+
+// --- search_memory 默认第一屏给多少正文（2026-10-05）---
+
+/**
+ * `formatSearchResults` 出哪种样式——search_memory 默认档（detail_level=normal）、命令行 `search`、本地 UI 共用：
+ *   fulltext — 默认（2026-10-05 起，Alice 看过第一屏盲判后拍板）：按名次给正文全文，单条封顶、总量有预算，
+ *              缩短过的条目写明共多少字、给了多少（memory-output.ts `formatFullTextResults`）
+ *   legacy   — 只在显式设 `legacy` 时走：改动之前的表格 + 每条 120 字片段，逐字节不变。
+ *              退回旧样式只要在 mcp.env 里加这一行；已经开着的进程要重启才读得到。
+ */
+export const searchFirstScreen = (): "legacy" | "fulltext" =>
+  process.env.RECALLNEST_SEARCH_FIRST_SCREEN === "legacy" ? "legacy" : "fulltext";
+
+// --- 对话原文入库（2026-10-06 起默认关）---
+
+/**
+ * `ingest` 要不要把对话记录（cc / codex / kimi / gemini / desktop / minis）切块、嵌入、写进 memories 表：
+ *   false — 默认（2026-10-06 起，Alice 拍板）：对话原文由 Deja 统一树索引，记忆库只放提炼产物。
+ *           这六个来源不切片不嵌入；Minis 投递目录里的文件照样挪进 data/minis-archive（Deja 从那里读）；
+ *           记忆文件对账照常。
+ *   true  — 只在显式设 `on` 时走：回到改动之前的行为。切块与入库的代码都还在（src/ingest.ts、
+ *           src/event-segmenter.ts），重开只要在跑 ingest 的环境里加这一行；要把关掉期间以及此前的会话
+ *           全部重新入库，先把 data/ingested-files.json 挪走再跑。Minis 例外：关着的时候它的文件已经从
+ *           投递目录挪进 data/minis-archive，入库不扫那个目录，要补就把想补的文件从存档拷回投递目录再跑
+ *           （拷，不是挪；跑完它们会被再挪回存档，同名同内容不会多存一份）。
+ * 只认 `on` 这一个写法。
+ */
+export const transcriptIngest = (): boolean => process.env.RECALLNEST_TRANSCRIPT_INGEST === "on";
+
+/**
+ * RECALLNEST_CHECKPOINT_MIRROR（2026-10-07）：checkpoint 存完后要不要同步镜像进记忆库（src/checkpoint-mirror.ts）。
+ * 默认开；只认 `off` 这一个写法来关。另有文件开关 data/checkpoint-mirror.off，每次调用时读，
+ * 已经在跑的进程不用重启就停（环境变量只在进程启动时读进来）。
+ */
+export const checkpointMirror = (): boolean => process.env.RECALLNEST_CHECKPOINT_MIRROR !== "off";
+
 // --- String settings with `||` default (empty string falls through) ---
 
 export const dataDir = (): string => process.env.RECALLNEST_DATA_DIR || "data";
@@ -146,6 +252,36 @@ export const synthesisModel = (): string | undefined => {
   return trimmed ? trimmed : undefined;
 };
 
+/**
+ * Per-request timeout (ms) for the embedding client, overriding `embedding.timeoutMs`
+ * in config.json.
+ *
+ * Exists so the timeout can be set per deployment (the resident MCP server, a one-off
+ * CLI ingest) without editing the shared config file — the same reason
+ * `RECALLNEST_LAYER_ADMISSION` lives here.
+ *
+ * Unset / empty / non-finite / <= 0 → undefined, i.e. fall through to config.json and
+ * ultimately to the SDK default. **Not setting it anywhere keeps the old behavior.**
+ */
+export const embeddingTimeoutMs = (): number | undefined => {
+  const raw = process.env.RECALLNEST_EMBEDDING_TIMEOUT_MS;
+  if (raw === undefined || raw.trim() === "") return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+};
+
+/**
+ * 记忆文件对账（memory-reconcile.ts）单轮下架上限，覆盖默认的 max(300, 活跃文档切片数的 25%)。
+ * 首轮存量清理用 `reconcile-memory --max-retire` 放行更合适；这个变量留给「某台部署想长期调严 / 调松」。
+ * 未设 / 空 / 非有限数 / 负数 → undefined，走默认公式；0 是合法值（本部署只插入不下架）。
+ */
+export const memoryReconcileMaxRetire = (): number | undefined => {
+  const raw = process.env.RECALLNEST_MEMORY_RECONCILE_MAX_RETIRE;
+  if (raw === undefined || raw.trim() === "") return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : undefined;
+};
+
 // --- Raw env values (caller validates / clamps / falls back to config) ---
 
 export const recallModeRaw = (): string | undefined => process.env.RECALLNEST_RECALL_MODE;