@0xmaxma/claude-gateway 1.6.8 → 1.7.0

package/dist/ui/web-ui.js.map

@@ -1 +1 @@
-{"version":3,"file":"web-ui.js","sourceRoot":"","sources":["../../src/ui/web-ui.ts"],"names":[],"mappings":";;AAIA,sDAq4BC;AAQD,8CAiFC;AAl+BD;;;GAGG;AACH,SAAgB,qBAAqB;IACnC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAm4BD,CAAC;AACT,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,cAAc,GAAG,EAAE;IACnD,MAAM,UAAU,GAAG,cAAc;SAC9B,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC9F,+EAA+E;IAC/E,8EAA8E;IAC9E,MAAM,SAAS,GAAG,UAAU;QAC1B,CAAC,CAAC;uBACiB,UAAU,QAAQ;QACrC,CAAC,CAAC;;;;;;;YAOM,CAAC;IACX,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA6BH,CAAC;AACT,CAAC"}
+{"version":3,"file":"web-ui.js","sourceRoot":"","sources":["../../src/ui/web-ui.ts"],"names":[],"mappings":"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"}

package/mcp/package.json

@@ -4,7 +4,8 @@
   "type": "module",
   "bin": "./server.ts",
   "scripts": {
-    "start": "bun install --no-summary && bun server.ts"
+    "start": "bun install --no-summary && bun server.ts",
+    "test": "bun test"
   },
   "dependencies": {
     "@line/bot-sdk": "^11.0.2",

package/mcp/server.ts

@@ -23,6 +23,7 @@ import { ImageModule } from './tools/image/module';
 import { ShareImageModule } from './tools/share-image/module';
 import { AppsModule } from './tools/apps/module';
 import { ApiModule } from './tools/api/module';
+import { MemoryModule } from './tools/memory/module';
 import { buildChannelInstructions } from './instructions';
 import type { ChannelModule, ToolModule, McpToolDefinition } from './types';
 
@@ -46,6 +47,7 @@ const modules: AnyModule[] = [
   new ShareImageModule(),
   new AppsModule(),
   new ApiModule(),
+  new MemoryModule(),
 ];
 
 // Build tool-to-module mapping for enabled modules

package/mcp/tools/image/module.ts

@@ -60,6 +60,20 @@ const ERROR_HINTS: Record<string, string> = {
 type JobResponse = {
   task_id?: string;
   status?: 'queued' | 'running' | 'done' | 'failed';
+  // What actually generated (or is generating) the image — the image service now
+  // echoes these on every poll, so a status re-poll in a LATER turn (which no
+  // longer has the original generate call's "model" argument in scope) can
+  // still recover them instead of falling back to "unknown".
+  provider?: string;
+  model?: string;
+  // The upstream provider's OWN task id — distinct from this job's own
+  // task_id (the image service's own job id, used for polling). A live E2E test
+  // caught that these are two separate id spaces: the image provider's own
+  // Store is keyed by ITS OWN ids, so a later resume request naming the wrong
+  // (outer) id silently fails to resolve. THIS is the id that must be
+  // persisted for continue_from to ever work. Absent for providers with no
+  // resume concept.
+  provider_task_id?: string;
   byok?: boolean;
   cost?: number;
   images?: string[];
@@ -279,11 +293,44 @@ export class ImageModule implements ToolModule {
       if (rawImage && rawImages) {
         return { content: [{ type: 'text', text: 'generate_image: pass either "image" or "images", not both.' }], isError: true };
       }
-      const normalized = await this.normalizeRefs(rawImage ? [rawImage] : rawImages!);
+      const refsList = rawImage ? [rawImage] : rawImages!;
+      const normalized = await this.normalizeRefs(refsList);
       if ('error' in normalized) return normalized.error;
       mintedShareIds = normalized.mintedShareIds;
       if (rawImage) reqBody.image = normalized.urls[0];
       else reqBody.images = normalized.urls;
+
+      // continue_from is the LLM's sole judgment call on
+      // whether this is a true continuation of a prior own-generation, not
+      // just a visual reference. Resolve it to that ref's provider task id —
+      // found ONLY by locating a matching artifact: entry among the refs just
+      // normalized above (never invented, never taken on faith). No match, or
+      // a match with no recorded task id (path ref, or an artifact with none)
+      // → silently omitted, exactly like any other unresolved resume signal
+      // downstream; never an error.
+      // Defensively strip a leading "artifact:" — the schema asks for the bare
+      // id, but tolerate the prefixed form rather than silently failing to match.
+      const continueFrom = (typeof args.continue_from === 'string' ? args.continue_from.trim() : '').replace(/^artifact:/i, '');
+      if (continueFrom) {
+        const idx = refsList.findIndex((r) => r.trim() === `artifact:${continueFrom}`);
+        const resumeTaskId = idx !== -1 ? normalized.taskIds[idx] : undefined;
+        if (resumeTaskId) {
+          reqBody.resume_task_id = resumeTaskId;
+        } else {
+          // Handoff-on-model-switch : resume isn't possible
+          // (no provider task id resolved — most commonly because a
+          // different model generated something since), but continue_from
+          // still signals a genuine continuation. Deterministically prepend
+          // the prompt that produced the referenced artifact — reused from
+          // stored data, not re-derived from the LLM's own memory, so it
+          // can't drift or balloon across a long edit chain (only ever ONE
+          // prior step is pulled in, never accumulated).
+          const priorPrompt = idx !== -1 ? normalized.priorPrompts[idx] : undefined;
+          if (priorPrompt) {
+            reqBody.prompt = `(Continuing from a prior edit: "${priorPrompt}") ${prompt}`;
+          }
+        }
+      }
     } else {
       if (rawImage) reqBody.image = rawImage;
       if (rawImages) reqBody.images = rawImages;
@@ -385,7 +432,15 @@ export class ImageModule implements ToolModule {
    */
   private async normalizeRefs(
     refs: string[],
-  ): Promise<{ urls: string[]; mintedShareIds: string[] } | { error: McpToolResult }> {
+  ): Promise<
+    | {
+        urls: string[];
+        mintedShareIds: string[];
+        taskIds: Array<string | undefined>;
+        priorPrompts: Array<string | undefined>;
+      }
+    | { error: McpToolResult }
+  > {
     const fail = (text: string): { error: McpToolResult } => ({
       error: { content: [{ type: 'text', text }], isError: true },
     });
@@ -445,10 +500,27 @@ export class ImageModule implements ToolModule {
         return fail('generate_image: image reference sharing requires gateway.publicUrl to be configured.');
       }
     }
-    // Merge back preserving the caller's order.
+    // Merge back preserving the caller's order. taskIds/priorPrompts are
+    // index-aligned with refs/urls — undefined for
+    // raw-URL entries and any local ref whose resolved artifact carries
+    // neither.
     let next = 0;
-    const urls = entries.map((e) => (e.kind === 'url' ? e.url : minted[next++]!.url!));
-    return { urls, mintedShareIds: minted.map((m) => m.share_id) };
+    const urls: string[] = [];
+    const taskIds: Array<string | undefined> = [];
+    const priorPrompts: Array<string | undefined> = [];
+    for (const e of entries) {
+      if (e.kind === 'url') {
+        urls.push(e.url);
+        taskIds.push(undefined);
+        priorPrompts.push(undefined);
+      } else {
+        const m = minted[next++]!;
+        urls.push(m.url!);
+        taskIds.push(m.task_id);
+        priorPrompts.push(m.prior_prompt);
+      }
+    }
+    return { urls, mintedShareIds: minted.map((m) => m.share_id), taskIds, priorPrompts };
   }
 
   private pollTimeoutMs(): number {
@@ -552,10 +624,19 @@ export class ImageModule implements ToolModule {
     // artifacts — file delivery is unaffected.
     let artifacts: Array<Record<string, unknown>> | undefined;
     if (shareBridgeEnabled() && files.length) {
+      // `model` (the caller's "provider/model" arg) is only known on the
+      // generate path (same-turn poll) — same limitation as `prompt` above.
+      // On an action="status" re-entry, fall back to job.provider/job.model,
+      // which the image service now echoes on every poll response for exactly
+      // this reason, instead of silently mislabeling the artifact "unknown".
       const slash = (model ?? '').indexOf('/');
-      const provider = slash > 0 ? (model as string).slice(0, slash) : 'unknown';
-      const modelName = slash > 0 ? (model as string).slice(slash + 1) : (model || 'unknown');
-      const registered = await registerArtifacts(files, { provider, model: modelName, taskId, prompt });
+      const provider = slash > 0 ? (model as string).slice(0, slash) : (job.provider || 'unknown');
+      const modelName = slash > 0 ? (model as string).slice(slash + 1) : (job.model || model || 'unknown');
+      // taskId (this job's own id, used for polling above) is NOT what
+      // gets persisted here — a resumable artifact must be keyed by the
+      // PROVIDER's own task id (job.provider_task_id), the id its Store
+      // actually recognizes. See the JobResponse.provider_task_id comment.
+      const registered = await registerArtifacts(files, { provider, model: modelName, taskId: job.provider_task_id, prompt });
       if (registered) {
         artifacts = registered.map((item, index) => ({
           artifact_id: item.artifact_id,
@@ -799,6 +880,14 @@ const imageToolDefs: McpToolDefinition[] = [
       'attach it with your reply tool and answer in one or two short sentences. Every extra step risks pushing ' +
       'the request past its timeout. ' +
       'action="status" polls a previously returned task_id. ' +
+      'PATIENCE: image generation can legitimately take several minutes — a "running" status (including the ' +
+      '"still generating, call again with action=status" note you get back when the local poll budget runs out) ' +
+      'is normal, not stuck. Keep calling action="status" with the SAME task_id until it resolves to done/failed. ' +
+      'Do NOT submit a new action="generate" call (on the same or a different model) for the same request while ' +
+      'an earlier task_id for it is still running — the earlier job may finish moments later, and you will have ' +
+      'generated and charged for the image twice while delivering only one. If you are genuinely considering ' +
+      'giving up after a long wait, say so to the user first in a normal reply and let them decide, instead of ' +
+      'silently abandoning the task_id and starting over. ' +
       'action="list" returns every available image model with its supported_qualities, supported_sizes, cost, and ' +
       'the capability flags supports_image_ref (image-to-image / edit) and supports_style_ref. Call it FIRST when ' +
       'choosing a model or when you need to know what a provider can do — you are NOT limited to the composer ' +
@@ -817,7 +906,15 @@ const imageToolDefs: McpToolDefinition[] = [
       'been reset while the chat history still has them): never answer "no images attached" to such a ' +
       'request before list_refs has returned an empty catalog. If the catalog makes the request ambiguous ' +
       '(or the requested index does not exist), ask the user which image they mean instead of guessing. ' +
-      'When the user selected options in the composer (an <image-params .../> tag in the turn), honor those values.',
+      'When the user selected options in the composer (an <image-params .../> tag in the turn), honor those values. ' +
+      'CONTINUING AN EDIT: some providers can resume the exact generation session behind an image instead of ' +
+      'treating it as a fresh visual reference. Set "continue_from" to that image\'s artifact id ONLY when ALL of ' +
+      'these hold: (1) you generated that image yourself earlier in this session (not something the user uploaded ' +
+      'or an external URL), (2) that same artifact id is also included in this call\'s "image"/"images", (3) this ' +
+      'call uses the SAME "model" that produced it, and (4) no OTHER model has generated any image in this session ' +
+      'since that image was made — even if you are back on the original model now, a model switch in between ' +
+      'breaks the continuation. If any of these do not hold, omit "continue_from" and rely on the plain image ' +
+      'reference instead — this is safe by default; the resume is a bonus when it applies, not a requirement.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -838,6 +935,14 @@ const imageToolDefs: McpToolDefinition[] = [
         image: { type: 'string', description: 'Optional reference image for image-to-image/edit: a media path (e.g. "media/xxx.png"), an "artifact:<id>" ref from a previous generate_image result, or an https URL. Local/artifact refs are converted to short-lived URLs automatically. ONLY pass this to a model whose supports_image_ref is true (check action="list"); for any other model, describe the reference image in the prompt instead of sending it here. Do not pass both "image" and "images".' },
         images: { type: 'array', items: { type: 'string' }, description: 'Optional multiple reference images (max 5; media paths, artifact:<id> refs, or https URLs — same supports_image_ref rule as "image"). Order is preserved.' },
         style: { type: 'string', description: 'Optional native style parameter (e.g. "vivid") — only for models whose supports_style_ref is true.' },
+        continue_from: {
+          type: 'string',
+          description:
+            'Optional artifact id (no "artifact:" prefix) of an image YOU generated earlier in THIS session, ' +
+            'also present in this call\'s "image"/"images", made with the SAME model as this call, with no OTHER ' +
+            'model generating any image since — see "CONTINUING AN EDIT" above for the full rule. Omit unless all ' +
+            'conditions clearly hold.',
+        },
         task_id: { type: 'string', description: 'Job id to poll (required for action="status").' },
       },
       required: [],

package/mcp/tools/memory/archive-reader.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Bun tests for the knowledge-archive read path (planning-64 K1).
+ *
+ * Runs under Bun (`bun test`) because the reader uses `bun:sqlite` — the Node
+ * jest suite cannot load this module. The fixture DB is built with bun:sqlite
+ * using the SAME schema src/ writes under node:sqlite (external-content FTS5 +
+ * provenance/recall), so this exercises the real query path end to end.
+ */
+
+import { test, expect } from 'bun:test';
+import { Database } from 'bun:sqlite';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { searchArchive, getExcerpt, isMemoryScopedPath, archiveDbPath, sharedDbPathFromEnv, mergeHits } from './archive-reader';
+
+// Build a temp agent dir with a kb.sqlite carrying the given chunks.
+function mkAgentWithArchive(
+  chunks: Array<{ id: string; path: string; start: number; end: number; text: string; origin?: string; importance?: number }>,
+): { agentDir: string; workspaceDir: string; dbPath: string } {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(workspaceDir, { recursive: true });
+  const dbPath = archiveDbPath(workspaceDir); // agentDir/kb.sqlite
+
+  const db = new Database(dbPath);
+  db.exec('PRAGMA foreign_keys=ON');
+  db.exec(`
+    CREATE TABLE kb_chunks (rowid_id INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT UNIQUE, path TEXT,
+      start_line INTEGER, end_line INTEGER, text TEXT, updated_at INTEGER);
+    CREATE TABLE kb_chunk_recall (chunk_id TEXT PRIMARY KEY, importance INTEGER, triggers TEXT, project_key TEXT,
+      FOREIGN KEY (chunk_id) REFERENCES kb_chunks(id) ON DELETE CASCADE);
+    CREATE TABLE kb_chunk_provenance (chunk_id TEXT PRIMARY KEY, origin_class TEXT, session_kind TEXT,
+      observed_at INTEGER, supersedes_key TEXT, FOREIGN KEY (chunk_id) REFERENCES kb_chunks(id) ON DELETE CASCADE);
+    CREATE VIRTUAL TABLE kb_chunks_fts USING fts5(text, content='kb_chunks', content_rowid='rowid_id');
+    CREATE TRIGGER kb_chunks_ai AFTER INSERT ON kb_chunks BEGIN
+      INSERT INTO kb_chunks_fts(rowid, text) VALUES (new.rowid_id, new.text);
+    END;
+  `);
+  const ins = db.prepare('INSERT INTO kb_chunks(id,path,start_line,end_line,text,updated_at) VALUES(?,?,?,?,?,?)');
+  const insR = db.prepare('INSERT INTO kb_chunk_recall(chunk_id,importance) VALUES(?,?)');
+  const insP = db.prepare('INSERT INTO kb_chunk_provenance(chunk_id,origin_class,session_kind,observed_at) VALUES(?,?,?,?)');
+  for (const c of chunks) {
+    ins.run(c.id, c.path, c.start, c.end, c.text, 1);
+    insR.run(c.id, c.importance ?? null);
+    insP.run(c.id, c.origin ?? 'agent', 'unknown', 1);
+  }
+  db.close();
+  return { agentDir, workspaceDir, dbPath };
+}
+
+test('isMemoryScopedPath: accepts memory-scoped, rejects traversal/abs/out-of-scope', () => {
+  expect(isMemoryScopedPath('MEMORY.md')).toBe(true);
+  expect(isMemoryScopedPath('USER.md')).toBe(true);
+  expect(isMemoryScopedPath('memory/foo.md')).toBe(true);
+  expect(isMemoryScopedPath('memory/sub/bar.md')).toBe(true);
+  expect(isMemoryScopedPath('../secret.md')).toBe(false);
+  // The discriminating case: ends in .md AND starts with memory/, so ONLY the
+  // ".." guard rejects it — proves that guard is load-bearing.
+  expect(isMemoryScopedPath('memory/../secret.md')).toBe(false);
+  expect(isMemoryScopedPath('memory/../../etc/passwd')).toBe(false);
+  expect(isMemoryScopedPath('/etc/passwd')).toBe(false);
+  expect(isMemoryScopedPath('notes/random.md')).toBe(false);
+  expect(isMemoryScopedPath('AGENTS.md')).toBe(false);
+});
+
+test('searchArchive: FTS match returns ranked hit with provenance + importance', () => {
+  const { workspaceDir, agentDir } = mkAgentWithArchive([
+    { id: 'memory/getpod.md#1-1', path: 'memory/getpod.md', start: 1, end: 1, text: 'Getpod ingress returns 401 before the gateway', origin: 'agent', importance: 7 },
+    { id: 'memory/apps.md#1-1', path: 'memory/apps.md', start: 1, end: 1, text: 'apps router mounts under gateway-router', origin: 'agent' },
+  ]);
+  try {
+    const hits = searchArchive(archiveDbPath(workspaceDir), 'ingress 401', 6);
+    expect(hits.length).toBe(1);
+    expect(hits[0].path).toBe('memory/getpod.md');
+    expect(hits[0].originClass).toBe('agent');
+    expect(hits[0].importance).toBe(7);
+    expect(hits[0].startLine).toBe(1);
+    expect(typeof hits[0].score).toBe('number');
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+// Regression (#351): a kb.sqlite built before the planning-66 `entry_hash`
+// column (exactly what `mkAgentWithArchive` produces) must not crash the read
+// path with `no such column: entry_hash`. searchArchive heals the column in
+// place and returns hits with entryHash=null. Proven to throw on pre-fix code.
+test('searchArchive: DB missing entry_hash column does not throw and heals it', () => {
+  const { workspaceDir, agentDir } = mkAgentWithArchive([
+    { id: 'memory/x.md#1-1', path: 'memory/x.md', start: 1, end: 1, text: 'ingress 401 token mismatch', origin: 'agent' },
+  ]);
+  const dbPath = archiveDbPath(workspaceDir);
+  const cols = (dbPath: string): string[] => {
+    const d = new Database(dbPath, { readonly: true });
+    try {
+      return (d.query(`PRAGMA table_info(kb_chunks)`).all() as Array<{ name: string }>).map((c) => c.name);
+    } finally {
+      d.close();
+    }
+  };
+  try {
+    // Precondition: the pre-#346 fixture genuinely lacks the column.
+    expect(cols(dbPath)).not.toContain('entry_hash');
+
+    let hits: ReturnType<typeof searchArchive> = [];
+    expect(() => {
+      hits = searchArchive(dbPath, 'ingress 401', 6);
+    }).not.toThrow();
+    expect(hits.length).toBe(1);
+    expect(hits[0].path).toBe('memory/x.md');
+    expect(hits[0].entryHash).toBeNull();
+
+    // The read path healed the DB in place so subsequent writers/readers are safe.
+    expect(cols(dbPath)).toContain('entry_hash');
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+test('searchArchive: missing DB → [], empty/punctuation query → []', () => {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(workspaceDir, { recursive: true });
+  try {
+    expect(searchArchive(archiveDbPath(workspaceDir), 'anything', 6)).toEqual([]); // no kb.sqlite
+    const { workspaceDir: ws2, agentDir: dir2 } = mkAgentWithArchive([
+      { id: 'm#1-1', path: 'memory/a.md', start: 1, end: 1, text: 'hello world' },
+    ]);
+    expect(searchArchive(archiveDbPath(ws2), '   !!! ', 6)).toEqual([]); // no usable tokens
+    fs.rmSync(dir2, { recursive: true, force: true });
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+test('getExcerpt: bounded line range; out-of-scope/missing → null', () => {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(path.join(workspaceDir, 'memory'), { recursive: true });
+  fs.writeFileSync(path.join(workspaceDir, 'memory/note.md'), 'l1\nl2\nl3\nl4\nl5');
+  try {
+    const ex = getExcerpt(workspaceDir, 'memory/note.md', 2, 2);
+    expect(ex).not.toBeNull();
+    expect(ex!.text).toBe('l2\nl3');
+    expect(ex!.from).toBe(2);
+    expect(ex!.to).toBe(3);
+    expect(ex!.totalLines).toBe(5);
+    expect(ex!.truncated).toBe(true);
+
+    // Whole file → not truncated.
+    expect(getExcerpt(workspaceDir, 'memory/note.md', 1, 100)!.truncated).toBe(false);
+    // Out-of-scope path and missing file → null.
+    expect(getExcerpt(workspaceDir, '../secret.md', 1, 5)).toBeNull();
+    expect(getExcerpt(workspaceDir, 'memory/missing.md', 1, 5)).toBeNull();
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+test('sharedDbPathFromEnv: null when unset, <dir>/kb.sqlite when set (K3 corpus:shared)', () => {
+  const prev = process.env.GATEWAY_SHARED_KB_DIR;
+  try {
+    delete process.env.GATEWAY_SHARED_KB_DIR;
+    expect(sharedDbPathFromEnv()).toBeNull();
+    process.env.GATEWAY_SHARED_KB_DIR = '   ';
+    expect(sharedDbPathFromEnv()).toBeNull(); // blank → disabled
+    process.env.GATEWAY_SHARED_KB_DIR = '/tmp/shared/kb/global';
+    expect(sharedDbPathFromEnv()).toBe('/tmp/shared/kb/global/kb.sqlite');
+  } finally {
+    if (prev === undefined) delete process.env.GATEWAY_SHARED_KB_DIR;
+    else process.env.GATEWAY_SHARED_KB_DIR = prev;
+  }
+});
+
+test('mergeHits: round-robin interleave (bm25 not comparable across corpora), capped', () => {
+  const mk = (path: string, score: number) => ({
+    path, startLine: 1, endLine: 1, score, snippet: path, originClass: 'agent', importance: null,
+  });
+  // Each list is already best-first within its own corpus. A cross-corpus numeric
+  // sort would mix incomparable bm25 scales; interleave a,c,b instead (personal
+  // first each round), capped at the limit.
+  const merged = mergeHits([mk('a', -0.9), mk('b', -0.1)], [mk('c', -0.5), mk('d', -0.05)], 3);
+  expect(merged.map((h) => h.path)).toEqual(['a', 'c', 'b']);
+});
+
+test('mergeHits: interleave preserves per-corpus order even when scales differ', () => {
+  const mk = (path: string, score: number) => ({
+    path, startLine: 1, endLine: 1, score, snippet: path, originClass: 'agent', importance: null,
+  });
+  // Shared scores numerically "better" (more negative) must NOT starve the personal
+  // corpus — round-robin gives p1, s1, p2, s2.
+  const merged = mergeHits([mk('p1', -0.2), mk('p2', -0.05)], [mk('s1', -9), mk('s2', -8)], 4);
+  expect(merged.map((h) => h.path)).toEqual(['p1', 's1', 'p2', 's2']);
+});
+
+test('getExcerpt: a symlink inside memory/ escaping the workspace is refused', () => {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(path.join(workspaceDir, 'memory'), { recursive: true });
+  // A secret target OUTSIDE the workspace, and a memory/ symlink pointing at it.
+  const secret = path.join(agentDir, 'outside-secret.md');
+  fs.writeFileSync(secret, 'TOPSECRET outside the workspace');
+  fs.symlinkSync(secret, path.join(workspaceDir, 'memory', 'evil.md'));
+  try {
+    // Passes the string scope check (memory/*.md) but realpath escapes the ws → null.
+    expect(getExcerpt(workspaceDir, 'memory/evil.md', 1, 5)).toBeNull();
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});