@remnic/core 9.63.9 → 9.63.11

package/src/access-service.ts

@@ -278,6 +278,7 @@ import {
   recordMemoryOutcome,
 } from "./memory-worth-outcomes.js";
 import type { LcmMessagePartInput, MessagePartSourceFormat } from "./message-parts/index.js";
+import type { ObserveRequest, RecallRequest } from "./access-schema.js";
 import { recordObjectiveStateSnapshotsFromObservedMessages } from "./objective-state-writers.js";
 import { objectiveStateStoreOverrideForNamespace } from "./objective-state.js";
 import { offlineSyncStorageForSnapshot } from "./offline-sync-impression-drain.js";
@@ -373,17 +374,16 @@ function normalizeTrustZoneInputError(error: unknown): EngramAccessInputError |
 
 export const ENGRAM_ACCESS_WRITE_SCHEMA_VERSION = 1;
 
-export interface EngramAccessRecallRequest {
-  query: string;
-  sessionKey?: string;
-  namespace?: string;
+/**
+ * Recall request. Wire fields derive from the canonical zod schema
+ * (`recallRequestSchema`, access-schema.ts — issue #2482) so the HTTP body,
+ * the MCP args, and the service share ONE model. The overlay below carries
+ * server-resolved transport fields no client may set.
+ */
+export interface EngramAccessRecallRequest extends RecallRequest {
   authenticatedPrincipal?: string;
   /** Trusted connector identity resolved at the transport boundary. */
   sourceConnector?: string;
-  idempotencyKey?: string;
-  topK?: number;
-  mode?: RecallPlanMode | "auto";
-  includeDebug?: boolean;
   abortSignal?: AbortSignal;
   /**
    * Internal, server-set field (issue #1906): wall-clock ms the caller
@@ -393,70 +393,6 @@ export interface EngramAccessRecallRequest {
    * (same pattern as `abortSignal`).
    */
   queueWaitMs?: number;
-  /**
-   * Recall disclosure depth. Omitting it preserves the `"chunk"` default.
-   * Other accepted values are `"section"` and `"raw"`.
-   */
-  disclosure?: RecallDisclosure;
-  /**
-   * Coding-agent context (issue #569). When a connector resolves a git
-   * context for the session's cwd, it passes it here and the access service
-   * attaches it to the orchestrator before recall so project- / branch-
-   * scoped namespace overlays apply.
-   *
-   * Keyed by `sessionKey`; ignored when `sessionKey` is absent.
-   */
-  codingContext?: {
-    projectId: string;
-    branch: string | null;
-    rootPath: string;
-    defaultBranch: string | null;
-  } | null;
-  /**
-   * Working directory of the calling agent session. When provided and no
-   * `codingContext` is already attached to the session, the service resolves
-   * git context from this path and attaches it automatically. This enables
-   * Claude Code hooks (and any connector that knows its cwd) to get
-   * project-scoped memory without explicitly constructing a `codingContext`.
-   */
-  cwd?: string;
-  /**
-   * Arbitrary project tag for non-git-based project scoping. When provided,
-   * creates a `CodingContext` with `projectId: "tag:<projectTag>"`.
-   * Useful for OpenClaw sessions where the whole workspace is one git repo
-   * but different conversations correspond to different client projects.
-   * Takes precedence over `cwd`-based git resolution but NOT over an
-   * explicit `codingContext`.
-   */
-  projectTag?: string;
-  /**
-   * Historical recall pin (issue #680).  ISO 8601 timestamp.  When set,
-   * the orchestrator filters out memories whose `valid_at` is after this
-   * instant OR whose `invalid_at` is at-or-before this instant, so the
-   * caller sees the corpus as it existed at `asOf`.  Invalid values are
-   * rejected here with `EngramAccessInputError` (CLAUDE.md rule 51).
-   */
-  asOf?: string;
-  /**
-   * Free-form recall tag filter (issue #689). When non-empty, recall results
-   * whose frontmatter `tags` do not match are removed from the response.
-   * Comparison is case-sensitive exact match against tags stored on each
-   * memory's frontmatter (see `storage.ts` and `docs/tags.md`).
-   */
-  tags?: string[];
-  /**
-   * Match mode for `tags` (issue #689). `"any"` (default when omitted)
-   * admits results that carry at least one filter tag. `"all"` requires
-   * every filter tag to be present. Ignored when `tags` is absent or empty.
-   */
-  tagMatch?: "any" | "all";
-  /**
-   * Issue #681 — when `true`, bypasses the configured
-   * `graphTraversalConfidenceFloor` for this recall and includes graph edges
-   * below the floor in traversal.  Useful for diagnostic queries that need to
-   * surface results pruned by confidence decay.  Default `false`.
-   */
-  includeLowConfidence?: boolean;
 }
 
 /**
@@ -1033,27 +969,18 @@ export interface EngramAccessObserveMessage {
   sourceFormat?: MessagePartSourceFormat;
 }
 
-export interface EngramAccessObserveRequest extends SourceConnectorProvenance {
-  sessionKey: string;
+/**
+ * Observe request. Wire fields derive from the canonical zod schema
+ * (`observeRequestSchema`, access-schema.ts — issue #2482); the service
+ * consumes the transport-cleaned message form (the wire schema tolerates
+ * nullable `parts`/`sourceFormat`, the service maps them to `undefined`).
+ */
+export interface EngramAccessObserveRequest
+  extends Omit<ObserveRequest, "messages">,
+    SourceConnectorProvenance {
   messages: EngramAccessObserveMessage[];
-  namespace?: string;
   authenticatedPrincipal?: string;
-  skipExtraction?: boolean;
-  /** Optional idempotency key (issue #1649): a retried POST with the same key is deduplicated server-side; divergent reuse is a conflict. */
-  idempotencyKey?: string;
-  /**
-   * Working directory of the calling agent session (issue #569 wiring).
-   * When provided and no `codingContext` is attached for this session,
-   * resolves git context from the path and attaches it so writes route to
-   * the correct project namespace.
-   */
-  cwd?: string;
-  /**
-   * Arbitrary project tag for non-git-based project scoping (issue #569).
-   * Creates a `CodingContext` with `projectId: "tag:<projectTag>"`.
-   */
-  projectTag?: string;
-  readonly suppressQuarantine?: boolean; // #1888: mirrors EngramAccessWriteEnvelope.suppressQuarantine (replay re-submit skips dead-lettering).
+  readonly suppressQuarantine?: boolean; // #1888: replay re-submit skips dead-lettering.
 }
 
 /**

package/src/briefing.test.ts

@@ -17,6 +17,7 @@ import {
   buildActiveThreads,
   buildBriefing,
   buildChainFollowupGenerator,
+  buildOpenCommitments,
   BRIEFING_FOLLOWUP_DEFAULT_MODEL,
 } from "./briefing.js";
 import type {
@@ -1670,3 +1671,52 @@ test("buildActiveThreads: primary sort by updatedAt overrides id tiebreaker", ()
   assert.equal(threads[0]!.id, "entity:beta", "newer timestamp must rank first, overriding id tiebreaker");
   assert.equal(threads[1]!.id, "entity:alpha");
 });
+
+// ──────────────────────────────────────────────────────────────────────────
+// buildOpenCommitments — non-English content (issue #2198)
+// ──────────────────────────────────────────────────────────────────────────
+function makeCommitmentMemory(overrides: {
+  content: string;
+  category?: MemoryFile["frontmatter"]["category"];
+  tags?: string[];
+}): MemoryFile {
+  return {
+    path: "/synthetic/mem.md",
+    frontmatter: {
+      id: "synthetic-commitment",
+      category: overrides.category ?? "fact",
+      created: "2026-08-17T00:00:00.000Z",
+      updated: "2026-08-17T00:00:00.000Z",
+      source: "test",
+      confidence: 0.9,
+      confidenceTier: "explicit",
+      tags: overrides.tags ?? [],
+    },
+    content: overrides.content,
+  };
+}
+
+test("buildOpenCommitments: fullwidth and Arabic question marks surface questions (issue #2198)", () => {
+  const fullwidth = makeCommitmentMemory({ content: "このAPIのレート制限はいくつですか？" });
+  const arabic = makeCommitmentMemory({ content: "ما هو موعد الاجتماع؟" });
+  const english = makeCommitmentMemory({ content: "What is the rate limit?" });
+
+  const commitments = buildOpenCommitments([fullwidth, arabic, english]);
+  assert.equal(commitments.length, 3);
+  assert.ok(commitments.every((c) => c.kind === "question"));
+});
+
+test("buildOpenCommitments: structured category is language-neutral (issue #2198)", () => {
+  const japanese = makeCommitmentMemory({
+    content: "金曜日までにレビューを提出する",
+    category: "commitment",
+  });
+  const commitments = buildOpenCommitments([japanese]);
+  assert.equal(commitments.length, 1);
+  assert.equal(commitments[0]!.kind, "commitment");
+});
+
+test("buildOpenCommitments: plain non-English statement without markers is not flagged", () => {
+  const plain = makeCommitmentMemory({ content: "会議は終わりました" });
+  assert.equal(buildOpenCommitments([plain]).length, 0);
+});

package/src/briefing.ts

@@ -1114,14 +1114,15 @@ export function buildRecentEntities(
     .slice(0, MAX_RECENT_ENTITIES);
 }
 
-function buildOpenCommitments(memories: MemoryFile[]): BriefingOpenCommitment[] {
+/** @internal — exported for testing only. */
+export function buildOpenCommitments(memories: MemoryFile[]): BriefingOpenCommitment[] {
   const commitments: BriefingOpenCommitment[] = [];
 
   for (const memory of memories) {
     const tags = memory.frontmatter.tags ?? [];
     const isPending = tags.some((t) => t.toLowerCase() === "pending");
     const isCommitment = memory.frontmatter.category === "commitment";
-    const isUnresolvedQuestion = /(?:\?$|\bfollow[- ]up\b|\btodo\b)/i.test(memory.content);
+    const isUnresolvedQuestion = /(?:[?？؟]$|\bfollow[- ]up\b|\btodo\b)/i.test(memory.content);
 
     if (isPending || isCommitment || isUnresolvedQuestion) {
       const kind: BriefingOpenCommitment["kind"] = isCommitment

package/src/chat/chat-engine.test.ts

@@ -123,6 +123,21 @@ test("confirmation protocol: isConfirmationMessage recognizes exact-match keywor
   assert.ok(!isConfirmationMessage("please apply"));
 });
 
+test("confirmation protocol: non-English exact-match confirmations (issue #2198)", () => {
+  assert.ok(isConfirmationMessage("はい"));
+  assert.ok(isConfirmationMessage("sí"));
+  assert.ok(isConfirmationMessage("ja"));
+  assert.ok(isConfirmationMessage("نعم"));
+  assert.ok(isConfirmationMessage("  JA  "));
+  assert.ok(isConfirmationMessage("Sí"));
+  // Exact match only — partial or hedged text keeps the no-apply default.
+  assert.ok(!isConfirmationMessage("si")); // missing accent, not exact
+  assert.ok(!isConfirmationMessage("jam"));
+  assert.ok(!isConfirmationMessage("ja, aber"));
+  assert.ok(!isConfirmationMessage("نعم لا"));
+  assert.ok(!isConfirmationMessage("はい、しかし"));
+});
+
 test("citation guard: uncited memory assertion gets warning", async () => {
   const executor = makeStubExecutor();
   // The LLM makes an assertion without calling any tools first.

package/src/chat/chat-engine.ts

@@ -85,10 +85,21 @@ export interface ChatEngineOptions {
 // Confirmation keywords — deterministic, not LLM-interpreted
 // ---------------------------------------------------------------------------
 
-const CONFIRMATION_KEYWORDS = new Set(["yes", "y", "apply", "confirm"]);
+// Exact-match confirmations. Unrecognized text keeps the conservative
+// no-apply default, so this stays a small fixed set (issue #2198).
+const CONFIRMATION_KEYWORDS: Record<string, true> = {
+  yes: true,
+  y: true,
+  apply: true,
+  confirm: true,
+  "はい": true, // Japanese
+  "sí": true, // Spanish
+  ja: true, // German/Dutch
+  "نعم": true, // Arabic
+};
 
 export function isConfirmationMessage(text: string): boolean {
-  return CONFIRMATION_KEYWORDS.has(text.trim().toLowerCase());
+  return CONFIRMATION_KEYWORDS[text.trim().toLowerCase()] === true;
 }
 
 // ---------------------------------------------------------------------------

package/src/day-summary.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Day-summary composition tests — bidi isolation of user content (issue #2198).
+ * All fixtures are synthetic — no real user data.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { formatDaySummaryMemories } from "./day-summary.js";
+import type { MemoryFile } from "./types.js";
+
+const FSI = "\u2068";
+const PDI = "\u2069";
+
+function makeMemory(content: string): MemoryFile {
+  return {
+    path: "/synthetic/mem.md",
+    frontmatter: {
+      id: "synthetic-mem",
+      category: "fact",
+      created: "2026-08-17T00:00:00.000Z",
+      updated: "2026-08-17T00:00:00.000Z",
+      source: "test",
+      confidence: 0.9,
+      confidenceTier: "explicit",
+      tags: [],
+    },
+    content,
+  };
+}
+
+test("formatDaySummaryMemories wraps RTL content in FSI/PDI isolates (issue #2198)", () => {
+  const rtl = makeMemory("اجتماع الفريق غدا في العاشرة");
+  const out = formatDaySummaryMemories([rtl]);
+
+  const expected = `[synthetic-mem] (fact, 2026-08-17T00:00:00.000Z)\n${FSI}اجتماع الفريق غدا في العاشرة${PDI}`;
+  assert.equal(out, expected);
+});
+
+test("formatDaySummaryMemories isolates LTR content too — labels stay outside the isolate", () => {
+  const out = formatDaySummaryMemories([makeMemory("standup at ten")]);
+
+  assert.ok(out.includes(`${FSI}standup at ten${PDI}`), "content wrapped in FSI/PDI");
+  assert.ok(out.startsWith("[synthetic-mem] (fact,"), "Latin label precedes the isolate");
+  assert.ok(!out.includes(`${PDI}[`), "label not inside the isolate");
+});
+
+test("formatDaySummaryMemories isolates each memory's content independently", () => {
+  const out = formatDaySummaryMemories([
+    makeMemory("first item"),
+    makeMemory("عنصر ثان"),
+  ]);
+
+  const parts = out.split("\n\n");
+  assert.equal(parts.length, 2);
+  assert.ok(parts[0]!.includes(`${FSI}first item${PDI}`));
+  assert.ok(parts[1]!.includes(`${FSI}عنصر ثان${PDI}`));
+});
+
+test("formatDaySummaryMemories raw-string passthrough is not wrapped", () => {
+  const out = formatDaySummaryMemories("  plain string input  ");
+  assert.equal(out, "plain string input");
+});

package/src/day-summary.ts

@@ -93,6 +93,18 @@ export async function loadDaySummaryPrompt(): Promise<string> {
   return EMBEDDED_DAY_SUMMARY_PROMPT;
 }
 
+const FSI = "\u2068"; // FIRST STRONG ISOLATE
+const PDI = "\u2069"; // POP DIRECTIONAL ISOLATE
+
+/**
+ * Wrap user content in Unicode bidi isolates so RTL text (Arabic, Hebrew)
+ * cannot reorder the surrounding Latin labels on the same composed line.
+ * No visible change for LTR content (issue #2198).
+ */
+function bidiIsolate(text: string): string {
+  return `${FSI}${text}${PDI}`;
+}
+
 export function formatDaySummaryMemories(memories: string | MemoryFile[]): string {
   if (typeof memories === "string") {
     return memories.trim();
@@ -102,7 +114,7 @@ export function formatDaySummaryMemories(memories: string | MemoryFile[]): strin
     .map((memory) => {
       const category = memory.frontmatter.category || "fact";
       const created = memory.frontmatter.created || "unknown";
-      return `[${memory.frontmatter.id}] (${category}, ${created})\n${memory.content}`;
+      return `[${memory.frontmatter.id}] (${category}, ${created})\n${bidiIsolate(memory.content)}`;
     })
     .join("\n\n")
     .trim();

package/src/entity-retrieval-i18n.test.ts

@@ -0,0 +1,115 @@
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import { normalizeEntityText } from "./entity-schema.js";
+import { buildEntityRecallSection } from "./entity-retrieval.js";
+import { detectNonEnglishEntityQueryMode } from "./entity-retrieval-i18n.js";
+import { StorageManager } from "./storage.js";
+import type { PluginConfig, TranscriptEntry } from "./types.js";
+
+function dialogueTurn(content: string): TranscriptEntry[] {
+  return [{
+    timestamp: new Date().toISOString(),
+    role: "user",
+    content,
+    sessionKey: "test-session",
+    turnId: "test-turn-1",
+  }];
+}
+
+function recallBase(
+  config: PluginConfig,
+  storage: StorageManager,
+  transcriptEntries: TranscriptEntry[],
+): Parameters<typeof buildEntityRecallSection>[0] {
+  return {
+    config,
+    storage,
+    query: "",
+    recentTurns: 2,
+    maxHints: 2,
+    maxSupportingFacts: 2,
+    maxRelatedEntities: 2,
+    maxChars: 10_000,
+    transcriptEntries,
+  };
+}
+
+test("non-English follow-ups resolve the recently discussed entity like the English pronoun follow-up (#2193)", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-entity-i18n-"));
+  try {
+    const storage = new StorageManager(memoryDir);
+    const entityRef = await storage.writeEntity("Alice", "person", []);
+    await storage.writeMemory("fact", "Alice leads the platform launch review.", {
+      source: "test",
+      entityRef,
+    });
+    const config = parseConfig({
+      openaiApiKey: "sk-test",
+      memoryDir,
+      workspaceDir: path.join(memoryDir, "workspace"),
+    });
+    const dialogue = dialogueTurn("I spoke with Alice about the launch review yesterday.");
+
+    // English pronoun follow-up and its Japanese/Chinese equivalents must
+    // resolve to the same recently-discussed entity.
+    for (const query of ["What about her?", "それで、どうなった？", "彼はどうなった？", "然后呢？"]) {
+      const section = await buildEntityRecallSection({
+        ...recallBase(config, storage, dialogue),
+        query,
+      });
+      assert.ok(section, `expected an entity hint section for query: ${query}`);
+      assert.match(section, /alice/i);
+    }
+
+    // Without recent dialogue both decline identically — no entity to carry.
+    for (const query of ["What about him?", "それで、どうなった？"]) {
+      const section = await buildEntityRecallSection({
+        ...recallBase(config, storage, []),
+        query,
+      });
+      assert.equal(section, null, `expected no entity section without dialogue: ${query}`);
+    }
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("zero-pronoun Japanese follow-up retrieves a CJK entity from a particle-bound mention (#2193)", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-entity-i18n-cjk-"));
+  try {
+    const storage = new StorageManager(memoryDir);
+    const entityRef = await storage.writeEntity("田中", "person", []);
+    await storage.writeMemory("fact", "田中は来週の発表を準備している。", {
+      source: "test",
+      entityRef,
+    });
+    const config = parseConfig({
+      openaiApiKey: "sk-test",
+      memoryDir,
+      workspaceDir: path.join(memoryDir, "workspace"),
+    });
+
+    for (const query of ["それで、どうなった？", "彼女はどうなった？"]) {
+      const section = await buildEntityRecallSection({
+        ...recallBase(config, storage, dialogueTurn("田中とは昨日打ち合わせをした。")),
+        query,
+      });
+      assert.ok(section, `expected an entity hint section for query: ${query}`);
+      assert.match(section, /田中/);
+    }
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("non-English query-mode cue table classification (#2193)", () => {
+  assert.equal(detectNonEnglishEntityQueryMode(normalizeEntityText("彼はどうなった")), "follow_up");
+  assert.equal(detectNonEnglishEntityQueryMode(normalizeEntityText("¿y ella?")), "follow_up");
+  assert.equal(detectNonEnglishEntityQueryMode(normalizeEntityText("田中さんの最近の状況")), "timeline");
+  assert.equal(detectNonEnglishEntityQueryMode(normalizeEntityText("了解しました")), null);
+});

package/src/entity-retrieval-i18n.ts

@@ -0,0 +1,161 @@
+import { normalizeEntityText } from "./entity-schema.js";
+
+/**
+ * Non-English query-mode cues for entity retrieval (#2193).
+ *
+ * #2161 made explicit entity mentions language-independent, but follow-up /
+ * pronoun coreference and timeline phrasing still classify through English
+ * word lists in `detectEntityQueryMode`. These cue tables plus the structural
+ * follow-up signal below close that gap without building a full coreference
+ * engine: the structural layer covers zero-pronoun scripts (Japanese,
+ * Chinese, Korean — languages that omit the subject entirely and can never
+ * trip a pronoun word list), and the tables add precision for other scripts,
+ * including Latin-script languages whose pronoun follow-ups carry their
+ * pronoun explicitly. Latin-script queries never use the structural layer:
+ * their generic technical questions ("what does this error mean?") are
+ * indistinguishable from subject-less follow-ups by shape alone.
+ */
+
+export type EntityQueryMode = "direct" | "timeline" | "follow_up";
+
+/** Shared short-question bound. Whitespace tokens are a poor length proxy
+ * for unspaced scripts, so bound graphemes too (48 graphemes ≈ 8 words). */
+const FOLLOW_UP_MAX_TOKENS = 8;
+const FOLLOW_UP_MAX_GRAPHEMES = 48;
+
+/** Latin letters mark a script with explicit pronouns; structural fallback
+ * never applies there (English "what does this error mean?" and its
+ * relatives keep the technical-question guard in detectEntityQueryMode). */
+const LATIN_LETTER_RE = /\p{Script=Latin}/u;
+
+ /** Latin / question marks: ASCII `?`, fullwidth `？` (CJK), Arabic `؟`. */
+ const QUESTION_MARK_RE = /[?？؟]/;
+
+/**
+ * CJK cues and normalized multi-word phrases match by containment; single
+ * Latin/Cyrillic/Arabic words match with a script-agnostic letter boundary
+ * so `él` never matches `el` and `il` never matches `famille`.
+ */
+const FOLLOW_UP_CONTAINS_CUES = [
+  // ja
+  "彼", "彼女", "あの人", "その人", "それで", "ちなみに",
+  // zh (simplified + traditional)
+  "他", "她", "它", "他们", "她们", "他們", "她們", "然后呢", "然後呢",
+  // ko
+  "그녀", "그 사람", "걔",
+] as const;
+
+const FOLLOW_UP_WORD_CUES = [
+  // es
+  "él", "ella", "ellos", "ellas",
+  // fr
+  "elle", "eux",
+  // de
+  "sie",
+  // pt
+  "ele", "ela",
+  // it
+  "lui", "lei",
+  // ru
+  "он", "она", "они",
+  // ar
+  "هو", "هي", "هم",
+] as const;
+
+const TIMELINE_CONTAINS_CUES = [
+  // ja
+  "最近", "その後", "どうなった", "何があった",
+  // zh (simplified + traditional)
+  "怎么样了", "怎麼樣了", "后来", "後來", "最新", "近况", "近況", "什么情况", "什麼情況",
+  // ko
+  "요즘", "요새", "최근",
+  // multi-word phrases, already in normalized form (punctuation → space)
+  "qué hay de nuevo", "qué pasó con", "quoi de neuf", "что нового",
+  "что случилось", "ما الجديد", "ماذا حدث", "was gibt s neues",
+] as const;
+
+function wordCueRegex(cues: readonly string[]): RegExp {
+  const alternation = cues
+    .map((cue) => cue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("|");
+  return new RegExp(`(?<![\\p{L}\\p{N}])(?:${alternation})(?![\\p{L}\\p{N}])`, "u");
+}
+
+const FOLLOW_UP_WORD_RE = wordCueRegex(FOLLOW_UP_WORD_CUES);
+
+function isShortFollowUpShaped(normalized: string): boolean {
+  if (!normalized) return false;
+  const tokens = normalized.split(/\s+/).filter(Boolean);
+  if (tokens.length > FOLLOW_UP_MAX_TOKENS) return false;
+  return Array.from(normalized).length <= FOLLOW_UP_MAX_GRAPHEMES;
+}
+
+/**
+ * Classify already-normalized non-English queries. Returns null when no
+ * table cue matches; callers keep their English rules untouched.
+ */
+export function detectNonEnglishEntityQueryMode(normalizedQuery: string): EntityQueryMode | null {
+  if (!normalizedQuery) return null;
+  if (
+    isShortFollowUpShaped(normalizedQuery)
+    && (
+      FOLLOW_UP_CONTAINS_CUES.some((cue) => normalizedQuery.includes(cue))
+      || FOLLOW_UP_WORD_RE.test(normalizedQuery)
+    )
+  ) {
+    return "follow_up";
+  }
+  if (TIMELINE_CONTAINS_CUES.some((cue) => normalizedQuery.includes(cue))) {
+    return "timeline";
+  }
+  return null;
+}
+
+/**
+ * Structural follow-up signal, independent of pronoun vocabulary: a short
+ * question carrying no entity name, asked while recent dialogue exists, is a
+ * coreference cue in zero-pronoun scripts (Latin-script queries are excluded
+ * above — their follow-ups carry pronouns that the cue tables and English
+ * rules classify). Recent-turn candidate resolution (and its empty result →
+ * section absent) remains the real gate, so this only routes the query into
+ * the follow-up path; it never invents an entity.
+ */
+export function isStructuralEntityFollowUpQuery(query: string, hasRecentDialogue: boolean): boolean {
+  if (!hasRecentDialogue) return false;
+  if (LATIN_LETTER_RE.test(query)) return false;
+  const normalized = normalizeEntityText(query);
+  return isShortFollowUpShaped(normalized) && QUESTION_MARK_RE.test(query);
+}
+
+const ENTITY_PRONOUN_RE = /\b(he|him|his|she|her|they|them|their|it|its)\b/i;
+
+export function detectEntityQueryMode(query: string): EntityQueryMode | null {
+  const normalized = normalizeEntityText(query);
+  if (!normalized) return null;
+  if (
+    /^(what about|and what about|how about|what happened (with|to) (he|him|his|she|her|they|them|their|it|its)|did (he|she|they|it)|is (he|she|they|it)|was (he|she|they|it))\b/.test(normalized)
+  ) {
+    return "follow_up";
+  }
+  if (
+    /^(who is|who s|what do we know about|what does|tell me about|what can you tell me about|what s new with|what happened with|what happened to|status of|where is|how is)\b/.test(normalized)
+  ) {
+    if (/^what does\b/.test(normalized)) {
+      if (/^what does (?:this|that|it|the|a|an|my|our|your|their)\b/.test(normalized)) {
+        return null;
+      }
+      if (
+        /^what does [a-z0-9-]+ (?:error|warning|exception|failure|stack|trace|code|message|log)\b/.test(normalized)
+        && /\b(mean|means|indicate|indicates|imply|implies)\b/.test(normalized)
+      ) {
+        return null;
+      }
+    }
+    return /what happened|what s new|status of|how is|where is/.test(normalized) ? "timeline" : "direct";
+  }
+  if (ENTITY_PRONOUN_RE.test(normalized) && normalized.split(/\s+/).length <= 8) {
+    return "follow_up";
+  }
+  return detectNonEnglishEntityQueryMode(normalized);
+}
+