@heretek-ai/epistemic-swarm 0.4.6 → 0.4.8

package/plugins/opencode/index.js

@@ -11,16 +11,35 @@
  * catalog. Schemas mirror runner/mcp_server.py build_tools() — keep in sync.
  */
 
-import { spawn } from 'child_process';
-import { readFileSync } from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
+import { spawn } from 'node:child_process';
+import { accessSync, constants, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PKG_ROOT = path.resolve(__dirname, '../..');
 const MCP_SERVER = path.join(PKG_ROOT, 'runner', 'mcp_server.py');
 
+function resolveBinary(name) {
+  const pathDirs = (process.env.PATH || '').split(path.delimiter);
+  for (const dir of pathDirs) {
+    if (!dir || dir === '.' || dir.startsWith('./') || dir.startsWith('../')) continue;
+    const full = path.join(dir, name);
+    try {
+      // Match Node's own PATH search: skip non-files and non-executables so a
+      // directory or a non-executable named `python3` earlier on PATH cannot
+      // shadow the real binary.
+      if (!statSync(full).isFile()) continue;
+      accessSync(full, constants.X_OK);
+      return realpathSync(full);
+    } catch {
+      /* not present, not a file, or not executable — keep searching */
+    }
+  }
+  return name;
+}
+
 /** Plugin version tracks package.json so it cannot drift across releases. */
 let PKG_VERSION = '0.0.0';
 try {
@@ -35,7 +54,7 @@ try {
  * Async (non-blocking spawn) so long swarms/audits never freeze the host
  * event loop; cancellation remains the host's prerogative.
  */
-function callMcp(tool, args = {}, cwd) {
+function callMcp(tool, args = {}, cwd = undefined) {
   return new Promise((resolve) => {
     let stdout = '';
     let stderr = '';
@@ -48,7 +67,7 @@ function callMcp(tool, args = {}, cwd) {
     let child;
     try {
       child = spawn(
-        'python3',
+        resolveBinary('python3'),
         [MCP_SERVER, 'call', tool, JSON.stringify(args || {})],
         {
           cwd: cwd || process.cwd(),
@@ -56,12 +75,12 @@ function callMcp(tool, args = {}, cwd) {
         }
       );
     } catch (err) {
-      done(String((err && err.message) || err), 'error');
+      done(String(err?.message || err), 'error');
       return;
     }
     child.stdout.on('data', (d) => { stdout += String(d); });
     child.stderr.on('data', (d) => { stderr += String(d); });
-    child.on('error', (err) => done(String((err && err.message) || err), 'error'));
+    child.on('error', (err) => done(String(err?.message || err), 'error'));
     child.on('close', (code) => done(stdout || stderr, code === 0 ? 'success' : 'error'));
   });
 }
@@ -449,16 +468,20 @@ export const OPENCODE_COMMANDS = [
 ];
 
 /**
- * Register the command catalog into an OpenCode config object without
- * overwriting user-defined commands of the same name. Exported for tests.
+ * Command catalog shaped for a declarative opencode config.
+ *
+ * V2's schema key is `commands` (plural) — `command` is the deprecated V1 key
+ * and is ignored by a V2 host. Registration on a live V2 host goes through
+ * `command.transform` instead of this; this exists so tests and docs can assert
+ * the catalog shape and the correct key.
  */
-export function registerOpenCodeCommands(cfg = {}) {
-  cfg.command ??= {};
+export function commandCatalog() {
+  const out = {};
   for (const cmd of OPENCODE_COMMANDS) {
-    if (cfg.command[cmd.name]) continue;
-    cfg.command[cmd.name] = { description: cmd.description, template: cmd.template };
+    if (!cmd?.name) continue;
+    out[cmd.name] = { description: cmd.description, template: cmd.template };
   }
-  return cfg;
+  return out;
 }
 
 /** Tool map (object form) for the server hook; array catalog stays canonical. */
@@ -469,7 +492,7 @@ function buildToolMap() {
       {
         ...tool,
         options: { codemode: false },
-        execute: async (args = {}, toolContext) =>
+        execute: async (args = {}, toolContext = undefined) =>
           callMcp(tool.name, normalizeArgs(tool.name, args), toolContext?.cwd),
       },
     ])
@@ -482,7 +505,7 @@ function buildToolMap() {
  * Reference pattern: @prevalentware/opencode-goal-plugin subscribes via
  * `context.event.subscribe({signal})`, detects idle as `session.idle` or an
  * idle `session.status`, continues via `context.session.prompt`, and preserves
- * state across compaction with the `experimental.session.compacting` hook.
+ * state across compaction with `context.session.hook("compaction", ...)`.
  * Every hook here is best-effort and never throws into the host.
  */
 
@@ -507,22 +530,31 @@ function readJsonFile(file) {
   }
 }
 
+function parseLedgerEntries(ledger) {
+  const stale = [];
+  const suspect = [];
+  const last = new Map();
+  for (const e of ledger) {
+    if (typeof e?.claim_id === 'string') last.set(e.claim_id, e.to_status);
+  }
+  for (const [id, s] of last) {
+    if (s === 'STALE') stale.push(id);
+    else if (s === 'SUSPECT') suspect.push(id);
+  }
+  const lastAt = ledger.at(-1)?.at ?? '';
+  return { stale, suspect, fingerprint: `${ledger.length}:${lastAt}` };
+}
+
 /** Last-write-wins degraded claims + requeue list. Pure fs reads. */
 export function readLedgerDegraded(root) {
   const out = { stale: [], suspect: [], requeued: [], fingerprint: 'empty' };
   try {
     const ledger = readJsonFile(path.join(root, '.research', 'ledger', 'claim_status.json'));
     if (Array.isArray(ledger)) {
-      const last = new Map();
-      for (const e of ledger) {
-        if (e && typeof e.claim_id === 'string') last.set(e.claim_id, e.to_status);
-      }
-      for (const [id, s] of last) {
-        if (s === 'STALE') out.stale.push(id);
-        else if (s === 'SUSPECT') out.suspect.push(id);
-      }
-      const lastAt = ledger.length > 0 ? ledger[ledger.length - 1]?.at : '';
-      out.fingerprint = `${ledger.length}:${lastAt}`;
+      const parsed = parseLedgerEntries(ledger);
+      out.stale = parsed.stale;
+      out.suspect = parsed.suspect;
+      out.fingerprint = parsed.fingerprint;
     }
     const requeue = readJsonFile(path.join(root, '.research', 'requeue.json'));
     if (Array.isArray(requeue)) {
@@ -635,6 +667,200 @@ export function startStalenessNudge(host, root) {
   }
 }
 
+/**
+ * Plugin log. Never throws.
+ *
+ * Before this existed every setup block swallowed errors with a bare
+ * `catch {}`, so `--log-level all` showed only host-side symptoms and a
+ * registration failure was indistinguishable from success.
+ */
+function log(host, level, message, detail) {
+  let text = message;
+  if (detail !== undefined) {
+    try {
+      text = `${message} ${JSON.stringify(detail)}`;
+    } catch {
+      text = `${message} [unserialisable detail]`;
+    }
+  }
+  try {
+    const sink = host?.client?.app?.log;
+    if (typeof sink === 'function') {
+      Promise.resolve(sink.call(host.client.app, {
+        body: { service: 'iumbtems', level, message: text },
+      })).catch(() => {});
+      return;
+    }
+  } catch {
+    /* fall through to console */
+  }
+  try {
+    (console.error || console.log)(`[iumbtems] ${level}: ${text}`);
+  } catch {
+    /* logging must never throw into the host */
+  }
+}
+
+function errDetail(err) {
+  return { error: String(err?.message ?? err) };
+}
+
+async function registerHostCommands(host) {
+  if (typeof host?.command?.transform !== 'function') return [];
+
+  // Snapshot which names are already taken *at setup time*. This snapshot is
+  // COPIED into the transform callback on every invocation and never grown.
+  //
+  // The host replays this callback on each command-registry rebuild, and the
+  // rebuilt registry starts from base config — so if the callback mutates a
+  // shared "already added" set, the second replay sees all six names as taken
+  // and adds nothing. That is exactly why the slash commands appeared at
+  // startup and vanished seconds later, and why only a full process restart
+  // brought them back (fresh setup -> fresh set).
+  //
+  // The reference plugin (@prevalentware/opencode-goal-plugin) gets this right
+  // with `const claimed = new Set(existingCommands)` inside the callback.
+  let existingNames = new Set();
+  try {
+    const listed = await host.command.list();
+    existingNames = new Set((listed?.data || []).map((c) => c?.name));
+  } catch (err) {
+    log(host, 'warn', 'command.list() failed; assuming an empty registry', errDetail(err));
+  }
+
+  const registration = await host.command.transform((draft) => {
+    const claimed = new Set(existingNames); // fresh copy per replay
+    const added = [];
+    for (const cmd of OPENCODE_COMMANDS) {
+      if (!cmd?.name || claimed.has(cmd.name)) continue;
+      claimed.add(cmd.name);
+      added.push(cmd.name);
+      draft.add({
+        name: cmd.name,
+        description: cmd.description,
+        execute: async (input) => {
+          const args = input?.prompt?.text || '';
+          const prompt = (typeof input?.prompt === 'object' && input?.prompt !== null) ? input.prompt : {};
+          await host.session.prompt({
+            ...prompt,
+            sessionID: input?.sessionID,
+            text: cmd.template.split('$ARGUMENTS').join(String(args).trim()),
+            delivery: input?.delivery,
+          });
+        },
+      });
+    }
+    log(host, 'debug', 'command.transform pass', {
+      added,
+      skippedAsPreexisting: [...existingNames].filter((n) => !added.includes(n)),
+    });
+  });
+
+  // Force materialisation now instead of waiting for the host's own later
+  // reconcile (which is the pass that used to wipe them).
+  try {
+    if (typeof host.command.reload === 'function') await host.command.reload();
+    log(host, 'info', 'slash commands registered', { count: OPENCODE_COMMANDS.length });
+  } catch (err) {
+    log(host, 'warn', 'command.reload() failed', errDetail(err));
+  }
+
+  return registration ? [registration] : [];
+}
+
+async function registerHostTools(host) {
+  if (typeof host?.tool?.transform !== 'function') return [];
+  const registration = await host.tool.transform((draft) => {
+    for (const [name, spec] of Object.entries(buildToolMap())) {
+      draft.add({
+        name,
+        description: spec.description,
+        input: spec.input,
+        options: { codemode: false },
+        execute: async (args = {}, toolContext = undefined) => {
+          const r = await callMcp(name, normalizeArgs(name, args), toolContext?.cwd);
+          return { content: r.content };
+        },
+      });
+    }
+    log(host, 'debug', 'tool.transform pass', { count: Object.keys(buildToolMap()).length });
+  });
+  try {
+    if (typeof host.tool.reload === 'function') await host.tool.reload();
+  } catch (err) {
+    log(host, 'warn', 'tool.reload() failed', errDetail(err));
+  }
+  return registration ? [registration] : [];
+}
+
+/**
+ * V2 compaction hook: keep .research state across context compaction.
+ *
+ * The V1 equivalent (`experimental.session.compacting`) lived in the old
+ * `server()` hook and was dead code on V2 — compaction silently lost the
+ * swarm state. Shape follows the reference plugin: push a text part onto
+ * `event.system`.
+ */
+async function registerCompactionHook(host, context) {
+  const hook = host?.session?.hook || context?.session?.hook;
+  if (typeof hook !== 'function') return [];
+  try {
+    const registration = await hook.call(host.session || context.session, 'compaction', async (event) => {
+      try {
+        const root =
+          event?.directory || host.location?.directory || context.location?.directory || event?.cwd;
+        if (!root) return;
+        const text = buildCompactionContext(root);
+        if (!text) return;
+        const system = Array.isArray(event?.system) ? event.system : null;
+        if (!system) return;
+        // Idempotent: the host may invoke this more than once per session.
+        if (system.some((part) => part?.type === 'text' && part?.text === text)) return;
+        system.push({ type: 'text', text });
+      } catch (err) {
+        log(host, 'warn', 'compaction hook failed', errDetail(err));
+      }
+    });
+    return registration ? [registration] : [];
+  } catch (err) {
+    log(host, 'warn', 'session.hook("compaction") unavailable', errDetail(err));
+    return [];
+  }
+}
+
+async function applyConfigOptions(host, opts, context) {
+  if (!opts || typeof opts !== 'object') return;
+  const updates = {};
+  if (opts.search_engine) updates.search_engine = opts.search_engine;
+  if (opts.max_iterations) updates.max_iterations = opts.max_iterations;
+  if (opts.mode) updates.mode = opts.mode;
+  if (opts.divergence_threshold !== undefined) {
+    updates.divergence_threshold = opts.divergence_threshold;
+  }
+  if (Object.keys(updates).length > 0) {
+    await callMcp(
+      'iumbtems_config',
+      updates,
+      host.location?.directory || context.location?.directory || host.cwd
+    );
+    log(host, 'debug', 'applied tuple options via iumbtems_config', updates);
+  }
+}
+
+function startNudgeSubscription(host, opts, context, cleanups) {
+  if (!(opts?.staleness_nudge ?? true)) return;
+  const nudgeHost = {
+    event: host.event || context.event,
+    session: host.session || context.session,
+  };
+  const root = host.location?.directory || context.location?.directory;
+  if (root) {
+    const stop = startStalenessNudge(nudgeHost, root);
+    if (typeof stop === 'function') cleanups.add(stop);
+    log(host, 'debug', 'staleness nudge subscription', { root, started: typeof stop === 'function' });
+  }
+}
+
 export function createOpenCodePlugin(context = {}) {
   return {
     id: 'heretek.iumbtems.epistemic-swarm',
@@ -643,127 +869,77 @@ export function createOpenCodePlugin(context = {}) {
     description:
       'I Use My Brain To Express My Self: High-integrity dialectic research, code audits, and open-source scouting',
 
-    server: async () => ({
-      // Config hook: slash-command catalog (mirrors the goal plugin's
-      // registerDesktopCommands pattern; never overwrites user commands).
-      config: (cfg) => registerOpenCodeCommands(cfg),
-      // Tool map (object form, as in the reference implementation).
-      tool: buildToolMap(),
-      // Compaction hook: preserve .research state (best-effort, silent skip
-      // when no workspace is present so compaction never breaks).
-      'experimental.session.compacting': async (input, output) => {
-        try {
-          const root = input?.directory ?? input?.location?.directory ?? process.cwd();
-          const ctx = buildCompactionContext(root);
-          if (ctx && output && Array.isArray(output.context)) output.context.push(ctx);
-        } catch {
-          /* never break compaction */
-        }
-      },
-    }),
-
+    // V2 only. The V1 `server()` factory and its `config` hook wrote the
+    // deprecated `command` key (V2's schema is `commands`), so they registered
+    // nothing on a V2 host — and carrying both shapes meant the real
+    // registration path had to guess which host it was talking to.
     setup: async (appContext) => {
       const host = appContext || {};
       const opts = context.options || host.options;
-      if (opts && typeof opts === 'object') {
-        const updates = {};
-        if (opts.search_engine) updates.search_engine = opts.search_engine;
-        if (opts.max_iterations) updates.max_iterations = opts.max_iterations;
-        if (opts.mode) updates.mode = opts.mode;
-        if (opts.divergence_threshold !== undefined) {
-          updates.divergence_threshold = opts.divergence_threshold;
-        }
-        if (Object.keys(updates).length > 0) {
-          await callMcp('iumbtems_config', updates, host.cwd);
-        }
+      // Transform registrations must precede any slow work: the host may
+      // reconcile past a slow setup and never see the commands.
+      const registrations = [];
+      const adopt = (list) => {
+        for (const r of list || []) if (r) registrations.push(r);
+      };
+
+      log(host, 'info', 'iumbtems setup', {
+        version: PKG_VERSION,
+        directory: host.location?.directory || context.location?.directory || null,
+      });
+
+      try {
+        adopt(await registerHostCommands(host));
+      } catch (err) {
+        log(host, 'error', 'registering slash commands failed', errDetail(err));
       }
-      // Phase C: idle staleness nudge (opt out with {staleness_nudge: false}).
-      // Subscribes only when the host exposes event/session; one per root.
       try {
-        if ((opts?.staleness_nudge ?? true)) {
-          const nudgeHost = {
-            event: host.event || context.event,
-            session: host.session || context.session,
-          };
-          const root =
-            host.location?.directory || context.location?.directory;
-          if (root) {
-            const stop = startStalenessNudge(nudgeHost, root);
-            if (typeof stop === 'function') setupCleanups.add(stop);
-          }
-        }
-      } catch {
-        /* lifecycle hooks are best-effort */
+        adopt(await registerHostTools(host));
+      } catch (err) {
+        log(host, 'error', 'registering tools failed', errDetail(err));
       }
-      // V2 host transforms (official dual-package pattern: V1 calls server(),
-      // V2 calls setup()). Registers slash commands + tools via the owning
-      // domains; each guarded so V1 hosts and partial V2 hosts keep working.
       try {
-        if (host.command && typeof host.command.transform === 'function') {
-          let existing = new Set();
-          try {
-            const listed = await host.command.list();
-            existing = new Set(((listed && listed.data) || []).map((c) => c && c.name));
-          } catch {
-            /* treat as empty */
-          }
-          await host.command.transform((draft) => {
-            for (const cmd of OPENCODE_COMMANDS) {
-              if (!cmd || !cmd.name || existing.has(cmd.name)) continue;
-              existing.add(cmd.name);
-              draft.add({
-                name: cmd.name,
-                description: cmd.description,
-                execute: async (input) => {
-                  const args = (input && input.prompt && input.prompt.text) || '';
-                  const prompt = (input && input.prompt && typeof input.prompt === 'object') ? input.prompt : {};
-                  await host.session.prompt({
-                    ...prompt,
-                    sessionID: input && input.sessionID,
-                    text: cmd.template.split('$ARGUMENTS').join(String(args).trim()),
-                    delivery: input && input.delivery,
-                  });
-                },
-              });
-            }
-          });
-        }
-      } catch {
-        /* command transform is best-effort */
+        adopt(await registerCompactionHook(host, context));
+      } catch (err) {
+        log(host, 'error', 'registering compaction hook failed', errDetail(err));
       }
+      // Slow work AFTER registration.
       try {
-        if (host.tool && typeof host.tool.transform === 'function') {
-          await host.tool.transform((draft) => {
-            for (const [name, spec] of Object.entries(buildToolMap())) {
-              draft.add({
-                name,
-                description: spec.description,
-                input: spec.input,
-                options: { codemode: false },
-                execute: async (args = {}, toolContext) => {
-                  const r = await callMcp(name, normalizeArgs(name, args), toolContext?.cwd);
-                  return { content: r.content };
-                },
-              });
-            }
-          });
-        }
-      } catch {
-        /* tool transform is best-effort */
+        await applyConfigOptions(host, opts, context);
+      } catch (err) {
+        log(host, 'warn', 'applying tuple options failed', errDetail(err));
       }
-      // Disposer: the host calls setup's return value as a cleanup function
-      // on unload/reload. It MUST be a function (returning a plain object
-      // crashes host reload with "not a function"). Aborts nudge streams so
-      // reloads never stack duplicate subscriptions.
-      return () => {
-        for (const stop of [...setupCleanups]) {
-          setupCleanups.delete(stop);
+      try {
+        startNudgeSubscription(host, opts, context, setupCleanups);
+      } catch (err) {
+        log(host, 'warn', 'starting staleness nudge failed', errDetail(err));
+      }
+
+      // The host calls this on unload/reload. It MUST be a function: returning
+      // a plain object used to abort the whole plugin reload with
+      // `TypeError: de is not a function`, dropping every registration.
+      return async () => {
+        let disposed = 0;
+        for (const registration of registrations) {
+          try {
+            await registration.dispose();
+            disposed += 1;
+          } catch (err) {
+            log(host, 'warn', 'registration.dispose() failed', errDetail(err));
+          }
+        }
+        registrations.length = 0;
+        let stopped = 0;
+        for (const stop of setupCleanups) {
           try {
             stop();
-          } catch {
-            /* cleanup is best-effort */
+            stopped += 1;
+          } catch (err) {
+            log(host, 'warn', 'cleanup failed', errDetail(err));
           }
         }
+        setupCleanups.clear();
+        log(host, 'info', 'iumbtems disposed', { registrations: disposed, nudges: stopped });
       };
     },
   };

package/plugins/opencode/tui.js

@@ -11,8 +11,8 @@
  * `keymap.layer` (inside a component scope), `api.theme`.
  */
 
-import { readFileSync, readdirSync, statSync } from 'fs';
-import path from 'path';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
 import { createElement, insert, setProp } from '@opentui/solid';
 import { createEffect, createSignal, onCleanup } from 'solid-js';
 import { OPENCODE_COMMANDS } from './index.js';
@@ -65,9 +65,8 @@ export function readSwarmStatus(root) {
     suspect: 0,
     requeued: 0,
   };
-  let entries = [];
   try {
-    entries = readdirSync(research);
+    readdirSync(research);
     status.workspace = true;
   } catch {
     return status;
@@ -149,7 +148,7 @@ function summarize(status) {
   return `IUMBTEMS: ${bits.join(' · ')}`;
 }
 
-function SwarmSidebar(api, root, sessionID) {
+function SwarmSidebar(api, root) {
   const colors = themeFg(api?.theme);
   const [snapshot, setSnapshot] = createSignal(readSwarmStatus(root));
   createEffect(() => {
@@ -162,7 +161,6 @@ function SwarmSidebar(api, root, sessionID) {
     }, REFRESH_MS);
     onCleanup(() => clearInterval(timer));
   });
-  void sessionID;
   return box({}, [
     () => {
       const s = snapshot();
@@ -196,7 +194,7 @@ function SwarmKeymapLayer(api) {
   // Every slash command gets a palette entry (usage toast; the host has no
   // programmatic slash-invoke API, so discovery + usage guidance is the win).
   for (const cmd of OPENCODE_COMMANDS || []) {
-    if (!cmd || !cmd.name) continue;
+    if (!cmd?.name) continue;
     commands.push({
       id: `iumbtems.command.${cmd.name}`,
       title: `/${cmd.name}`,
@@ -247,8 +245,8 @@ function registerSlot(api, name, render) {
 export function setupTui(api) {
   try {
     const root = resolveRoot(api);
-    const offSidebar = registerSlot(api, 'sidebar.content', (props) =>
-      SwarmSidebar(api, root, props?.sessionID)
+    const offSidebar = registerSlot(api, 'sidebar.content', () =>
+      SwarmSidebar(api, root)
     );
     const offApp = registerSlot(api, 'app', () => SwarmKeymapLayer(api));
     return () => {

package/plugins/research-cache/skills/research_cache/hasher.py

@@ -14,10 +14,14 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Dict, Any, Optional, Tuple
 
+DEFAULT_RESEARCH_DIR = ".research"
+BASE_DIR_HELP = "Base .research directory"
+
 class SourceHasher:
     def __init__(self, base_dir: Optional[Path] = None):
-        self.base_dir = base_dir or Path(".research")
-        self.sources_dir = self.base_dir / "sources"
+        target = base_dir or Path(DEFAULT_RESEARCH_DIR)
+        self.base_dir = Path(os.path.realpath(str(target)))
+        self.sources_dir = Path(os.path.realpath(str(self.base_dir / "sources")))
         self.sources_dir.mkdir(parents=True, exist_ok=True)
 
     @staticmethod
@@ -70,15 +74,28 @@ class SourceHasher:
         return None
 
     def _resolve_hash_file(self, hash_prefix: str, extension: str) -> Optional[Path]:
-        """Resolves exact or prefix hash to disk path."""
-        exact_path = self.sources_dir / f"{hash_prefix}{extension}"
+        """Resolves exact or prefix hash to disk path.
+
+        ``hash_prefix`` is untrusted (it arrives from an LLM tool call), so the
+        result is required to stay inside ``sources_dir``. Containment is checked
+        inline rather than via ``runner.path_safety`` because this module is
+        mirrored into the standalone ``research-cache`` plugin, which has no
+        ``runner`` package on its path.
+        """
+        if not re.match(r"^[a-fA-F0-9]+$", hash_prefix):
+            return None
+        exact_path = Path(os.path.realpath(str(self.sources_dir / f"{hash_prefix}{extension}")))
+        if exact_path.parent != self.sources_dir:
+            return None
         if exact_path.exists():
             return exact_path
 
         # If prefix match
         matches = list(self.sources_dir.glob(f"{hash_prefix}*{extension}"))
         if len(matches) == 1:
-            return matches[0]
+            candidate = Path(os.path.realpath(str(matches[0])))
+            if candidate.parent == self.sources_dir:
+                return candidate
         return None
 
     @staticmethod
@@ -143,20 +160,21 @@ def main():
     cache_parser.add_argument("--title", default="Untitled", help="Document Title")
     cache_parser.add_argument("--tier", default="WEB_DOCUMENT", help="Source tier")
     cache_parser.add_argument("--content", help="Raw text content (or read from stdin)")
-    cache_parser.add_argument("--dir", default=".research", help="Base .research directory")
+    cache_parser.add_argument("--dir", default=DEFAULT_RESEARCH_DIR, help=BASE_DIR_HELP)
 
     # Verify command
     verify_parser = subparsers.add_parser("verify", help="Verify a verbatim quote")
     verify_parser.add_argument("--hash", required=True, help="Document SHA-256 hash")
     verify_parser.add_argument("--quote", required=True, help="Verbatim quote to check")
-    verify_parser.add_argument("--dir", default=".research", help="Base .research directory")
+    verify_parser.add_argument("--dir", default=DEFAULT_RESEARCH_DIR, help=BASE_DIR_HELP)
 
     # List command
     list_parser = subparsers.add_parser("list", help="List cached sources")
-    list_parser.add_argument("--dir", default=".research", help="Base .research directory")
+    list_parser.add_argument("--dir", default=DEFAULT_RESEARCH_DIR, help=BASE_DIR_HELP)
 
     args = parser.parse_args()
-    hasher = SourceHasher(base_dir=Path(args.dir if hasattr(args, "dir") else ".research"))
+    dir_val = getattr(args, "dir", DEFAULT_RESEARCH_DIR) or DEFAULT_RESEARCH_DIR
+    hasher = SourceHasher(base_dir=Path(os.path.realpath(str(dir_val))))
 
     if args.command == "cache":
         content = args.content