@mnemonik/shared 1.0.0 → 5.75.3

package/src/codeScanner.ts

@@ -3,13 +3,14 @@
  */
 
 import { readdir, readFile, stat, lstat, realpath } from 'fs/promises';
-import { join, relative, extname } from 'path';
+import { join, relative, extname, sep } from 'path';
 import { createHash } from 'crypto';
 import { debug as logDebug } from './logger.js';
 import { withTimeout } from './asyncUtils.js';
+import { scrubSecrets } from './secretPatterns.js';
 
 /**
- * v2.46: File operation timeout (5 seconds) to prevent hanging on slow/unresponsive filesystems
+ * File operation timeout (5 seconds) to prevent hanging on slow/unresponsive filesystems
  */
 const FILE_OP_TIMEOUT_MS = 5000;
 
@@ -25,8 +26,8 @@ export interface CodeChunk {
     fileName: string;
     extension: string;
     size: number;
-    signature?: string; // v3.3: Function/class signature (e.g. "function foo(bar: string): number")
-    symbolName?: string; // v3.3: Symbol name (e.g. "foo")
+    signature?: string; // Function/class signature (e.g. "function foo(bar: string): number")
+    symbolName?: string; // Symbol name (e.g. "foo")
   };
 }
 
@@ -75,6 +76,14 @@ const DEFAULT_OPTIONS: Required<ScanOptions> = {
     '*.bundle.js',
     '*.legacy.js',
     '*.map',
+    // Agent-host transient checkouts. EnterWorktree creates isolated git
+    // worktree copies under `.claude/worktrees/{name}/`; indexing them
+    // duplicates the entire codebase under a path that misclassifies as
+    // `archive` doctype and polluted the dogfood corpus with 376 stale
+    // couplings. Glob form (with `*`) so the regex matcher applies it as a
+    // path predicate rather than a path-segment-equality predicate (which
+    // would not match the nested form).
+    '.claude/worktrees/*',
   ],
   includeExtensions: [
     '.ts',
@@ -97,6 +106,30 @@ const DEFAULT_OPTIONS: Required<ScanOptions> = {
   ],
 };
 
+/**
+ * Matchers for authority manifest / config / CI files whose verbatim content
+ * is collected by `collectAuthorityFiles` and pushed to the server for
+ * doc-truth Fingerprint parsing. Operates on relative, forward-slash paths.
+ */
+export const AUTHORITY_FILE_MATCHERS: Array<(relPath: string) => boolean> = [
+  (p) => p === 'package.json',
+  (p) => /^(packages|apps|services|tools)\/[^/]+\/package\.json$/.test(p),
+  (p) => p === 'tsconfig.json' || /^tsconfig\.[^/]+\.json$/.test(p),
+  (p) => p === 'pyproject.toml',
+  (p) => p === 'requirements.txt',
+  (p) => p === 'setup.py',
+  (p) => p === 'Cargo.toml',
+  (p) => p === 'Gemfile',
+  (p) => p === 'Makefile',
+  (p) => p === '.env.example',
+  (p) => /^\.github\/workflows\/[^/]+\.(yml|yaml)$/.test(p),
+  // SQL migrations: the schema_columns authority extractor reads every .sql
+  // under `migrations/` (listFiles('migrations/') -> LIKE 'migrations/%' then
+  // .endsWith('.sql')). Without collecting these, that authority is empty and
+  // every schema_table_enumeration claim falls to unverifiable.
+  (p) => /^migrations\/.*\.sql$/.test(p),
+];
+
 export class CodeScanner {
   private options: Required<ScanOptions>;
 
@@ -106,13 +139,13 @@ export class CodeScanner {
 
   /**
    * Maximum directory depth for recursive scanning
-   * v2.43: Prevents runaway recursion on deep/symlinked structures
+   * Prevents runaway recursion on deep/symlinked structures
    */
   private static readonly MAX_DEPTH = 10;
 
   /**
    * Scan a directory recursively and extract code chunks
-   * v2.43: Added max depth (10) to prevent infinite recursion
+   * Added max depth (10) to prevent infinite recursion
    */
   async scanDirectory(rootPath: string): Promise<CodeChunk[]> {
     const chunks: CodeChunk[] = [];
@@ -120,6 +153,73 @@ export class CodeScanner {
     return chunks;
   }
 
+  /**
+   * Enumerate scan-eligible relative file paths under `rootPath` without
+   * reading or chunking content. Same walk + ignorePatterns + extension
+   * filter as `scanDirectory`, but bounded to O(file count) directory ops
+   * — cheap enough to call on every periodic reconcile tick.
+   *
+   * Returns relative paths normalized against `rootPath`, matching the
+   * shape the server stores in `memories.metadata->>'filePath'`. Use this
+   * for the scanner reconciliation channel (`POST /api/v1/scan/reconcile`).
+   *
+   * Defensive: skips any path whose `relative()` result contains a `..`
+   * traversal segment (can happen when a symlink resolves under root but
+   * the readdir entry path doesn't normalize cleanly). The server's
+   * `safeScanPath` rejects such paths; filtering here keeps a single
+   * malformed entry from failing the entire reconcile push.
+   */
+  async listFiles(rootPath: string): Promise<string[]> {
+    const paths: string[] = [];
+    await this.traversePaths(rootPath, rootPath, paths, 0);
+    return paths.filter((p) => !/(^|[/\\])\.\.([/\\]|$)/.test(p));
+  }
+
+  private async traversePaths(
+    currentPath: string,
+    rootPath: string,
+    out: string[],
+    depth: number
+  ): Promise<void> {
+    if (depth >= CodeScanner.MAX_DEPTH) return;
+    try {
+      const entries = await withTimeout(
+        readdir(currentPath),
+        FILE_OP_TIMEOUT_MS,
+        `readdir timed out: ${currentPath}`
+      );
+      for (const entry of entries) {
+        const fullPath = join(currentPath, entry);
+        const relativePath = relative(rootPath, fullPath);
+        if (this.shouldIgnore(relativePath)) continue;
+
+        const lstats = await withTimeout(
+          lstat(fullPath),
+          FILE_OP_TIMEOUT_MS,
+          `lstat timed out: ${fullPath}`
+        );
+        if (lstats.isSymbolicLink()) {
+          const resolved = await realpath(fullPath);
+          const resolvedRoot = await realpath(rootPath);
+          if (!resolved.startsWith(resolvedRoot + '/') && resolved !== resolvedRoot) continue;
+        }
+        const stats = lstats.isSymbolicLink()
+          ? await withTimeout(stat(fullPath), FILE_OP_TIMEOUT_MS, `stat timed out: ${fullPath}`)
+          : lstats;
+
+        if (stats.isDirectory()) {
+          await this.traversePaths(fullPath, rootPath, out, depth + 1);
+        } else if (stats.isFile()) {
+          if (this.options.includeExtensions.includes(extname(fullPath))) {
+            out.push(relativePath);
+          }
+        }
+      }
+    } catch (error) {
+      logDebug('Error traversing directory (listFiles)', { path: currentPath, error });
+    }
+  }
+
   /**
    * Scan specific files and extract code chunks.
    * Pass rootPath to compute proper relative file paths in chunk metadata.
@@ -143,12 +243,26 @@ export class CodeScanner {
       }
     }
 
-    return chunks;
+    // Daemon-side secret redaction: scrub credentials from chunk content
+    // before they leave this process. contentHash is recomputed from the
+    // scrubbed content so the server-side dedup cache (which keys on
+    // contentHash) hits when team members push the same scrubbed text.
+    // Server still re-applies scrubSecrets in the /scan/push handler as
+    // defense in depth (idempotent).
+    return chunks.map((chunk) => {
+      const scrubbed = scrubSecrets(chunk.content);
+      if (scrubbed === chunk.content) return chunk;
+      return {
+        ...chunk,
+        content: scrubbed,
+        contentHash: this.hash(scrubbed),
+      };
+    });
   }
 
   /**
    * Recursively traverse directory
-   * v2.43: Added depth parameter with max limit
+   * Added depth parameter with max limit
    */
   private async traverseDirectory(
     currentPath: string,
@@ -156,14 +270,14 @@ export class CodeScanner {
     chunks: CodeChunk[],
     depth: number
   ): Promise<void> {
-    // v2.43: Prevent infinite recursion
+    // Prevent infinite recursion
     if (depth >= CodeScanner.MAX_DEPTH) {
       logDebug('Max directory depth reached, skipping', { path: currentPath, depth });
       return;
     }
 
     try {
-      // v2.46: Wrap readdir with timeout to prevent hanging
+      // Wrap readdir with timeout to prevent hanging
       const entries = await withTimeout(
         readdir(currentPath),
         FILE_OP_TIMEOUT_MS,
@@ -215,7 +329,7 @@ export class CodeScanner {
 
   /**
    * Check if path should be ignored
-   * v2.71: Fixed glob-to-regex conversion and substring matching.
+   * Fixed glob-to-regex conversion and substring matching.
    * - Escape regex special chars before replacing * with .*
    * - Replace ALL * occurrences (not just the first)
    * - For non-glob patterns, match on path segments to avoid false positives
@@ -238,14 +352,14 @@ export class CodeScanner {
 
   /**
    * Parse a file and extract code chunks
-   * v2.43: Added 10MB file size limit
+   * Added 10MB file size limit
    */
   private static readonly MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
 
   private async parseFile(filePath: string, rootPath: string): Promise<CodeChunk[]> {
     try {
-      // v2.43: Check file size before reading to avoid memory issues
-      // v2.46: Wrap stat with timeout
+      // Check file size before reading to avoid memory issues
+      // Wrap stat with timeout
       const stats = await withTimeout(
         stat(filePath),
         FILE_OP_TIMEOUT_MS,
@@ -260,7 +374,7 @@ export class CodeScanner {
         return [];
       }
 
-      // v2.46: Wrap readFile with timeout
+      // Wrap readFile with timeout
       const content = await withTimeout(
         readFile(filePath, 'utf-8'),
         FILE_OP_TIMEOUT_MS,
@@ -558,7 +672,7 @@ export class CodeScanner {
 
   /**
    * Extract structured chunks (functions, classes)
-   * v2.76: Uses brace-matching for TS/JS/Rust so nested braces are not truncated at first \n}
+   * Uses brace-matching for TS/JS/Rust so nested braces are not truncated at first \n}
    */
   private extractStructuredChunks(
     content: string,
@@ -604,7 +718,7 @@ export class CodeScanner {
           matchContent.length >= this.options.minChunkSize &&
           matchContent.length <= this.options.maxChunkSize
         ) {
-          // v3.3: Extract function/class signature and symbol name
+          // Extract function/class signature and symbol name
           const firstLine = matchContent.split('\n')[0].trim();
           const signature = firstLine.replace(/\{$/, '').trim() || undefined;
           const nameMatch = firstLine.match(
@@ -685,34 +799,106 @@ export class CodeScanner {
   }
 
   /**
-   * Fall back to raw chunking with overlap
+   * Raw chunking with overlap, bounded by character count (not line count).
+   *
+   * The previous implementation took `floor(maxChunkSize / 80)` lines per
+   * chunk on the assumption of ~80 chars/line. Long-line files (minified
+   * JS, JSON blobs, generated code) produced chunks many times larger than
+   * `maxChunkSize`, which then exceeded OpenAI's 8191-token embedding
+   * limit and surfaced as 400s on /scan/push (Sentry MNEMONIK-58).
+   *
+   * Now: walk lines and accumulate character length; emit when the next
+   * line would push the running total past `maxChunkSize`. Single lines
+   * longer than `maxChunkSize` are force-split into char-based segments.
+   * 10% overlap is carried by character count from the tail of the
+   * just-emitted chunk.
    */
   private chunkRaw(content: string, filePath: string, language: string, size: number): CodeChunk[] {
     const chunks: CodeChunk[] = [];
     const lines = content.split('\n');
-    const chunkSizeLines = Math.floor(this.options.maxChunkSize / 80); // Assume ~80 chars per line
-    const overlapLines = Math.floor(chunkSizeLines * 0.1); // 10% overlap
+    const maxBytes = this.options.maxChunkSize;
+    const minBytes = this.options.minChunkSize;
+    const overlapBytes = Math.floor(maxBytes * 0.1);
+    const fileName = filePath.split('/').pop() || '';
+    const extension = extname(filePath);
+
+    let currentLines: string[] = [];
+    let currentLen = 0;
+    let chunkStartIdx = 0;
+
+    const emit = (linesArr: string[], startIdx: number) => {
+      const text = linesArr.join('\n');
+      if (text.length < minBytes) return;
+      chunks.push({
+        content: text.trim(),
+        filePath,
+        language,
+        startLine: startIdx + 1,
+        endLine: startIdx + linesArr.length,
+        chunkType: 'raw',
+        contentHash: this.hash(text),
+        metadata: { fileName, extension, size },
+      });
+    };
 
-    for (let i = 0; i < lines.length; i += chunkSizeLines - overlapLines) {
-      const chunkLines = lines.slice(i, i + chunkSizeLines);
-      const chunkContent = chunkLines.join('\n');
+    const flushWithOverlap = () => {
+      if (currentLines.length === 0) return;
+      emit(currentLines, chunkStartIdx);
+
+      const overlapTail: string[] = [];
+      let overlapLen = 0;
+      for (let j = currentLines.length - 1; j >= 0; j--) {
+        const lineLen = currentLines[j].length + 1;
+        if (overlapLen + lineLen > overlapBytes) break;
+        overlapTail.unshift(currentLines[j]);
+        overlapLen += lineLen;
+      }
 
-      if (chunkContent.length >= this.options.minChunkSize) {
-        chunks.push({
-          content: chunkContent.trim(),
-          filePath,
-          language,
-          startLine: i + 1,
-          endLine: i + chunkLines.length,
-          chunkType: 'raw',
-          contentHash: this.hash(chunkContent),
-          metadata: {
-            fileName: filePath.split('/').pop() || '',
-            extension: extname(filePath),
-            size,
-          },
-        });
+      chunkStartIdx = chunkStartIdx + currentLines.length - overlapTail.length;
+      currentLines = overlapTail;
+      currentLen = overlapLen;
+    };
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (line.length >= maxBytes) {
+        if (currentLines.length > 0) {
+          emit(currentLines, chunkStartIdx);
+          currentLines = [];
+          currentLen = 0;
+        }
+        for (let offset = 0; offset < line.length; offset += maxBytes) {
+          const segment = line.slice(offset, offset + maxBytes);
+          if (segment.length < minBytes) continue;
+          chunks.push({
+            content: segment.trim(),
+            filePath,
+            language,
+            startLine: i + 1,
+            endLine: i + 1,
+            chunkType: 'raw',
+            contentHash: this.hash(segment),
+            metadata: { fileName, extension, size },
+          });
+        }
+        continue;
+      }
+
+      const lineLen = line.length + 1;
+      if (currentLen + lineLen > maxBytes && currentLen >= minBytes) {
+        flushWithOverlap();
       }
+
+      if (currentLines.length === 0) {
+        chunkStartIdx = i;
+      }
+      currentLines.push(line);
+      currentLen += lineLen;
+    }
+
+    if (currentLines.length > 0) {
+      emit(currentLines, chunkStartIdx);
     }
 
     return chunks;
@@ -724,4 +910,48 @@ export class CodeScanner {
   private hash(content: string): string {
     return createHash('sha256').update(content).digest('hex').substring(0, 16);
   }
+
+  /**
+   * Walk the project for authority manifest/config/CI files and return their
+   * verbatim content. Reuses ignorePatterns; matches AUTHORITY_FILE_MATCHERS
+   * (not includeExtensions). Content-only — no chunking, no embeddings.
+   */
+  async collectAuthorityFiles(
+    projectRoot: string
+  ): Promise<Array<{ path: string; content: string; hash: string }>> {
+    const out: Array<{ path: string; content: string; hash: string }> = [];
+
+    // M2: cap walk depth to match the scanner's MAX_DEPTH (10)
+    const walk = async (dir: string, depth: number): Promise<void> => {
+      if (depth >= CodeScanner.MAX_DEPTH) return;
+      let entries;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const ent of entries) {
+        const full = join(dir, ent.name);
+        const rel = relative(projectRoot, full).split(sep).join('/');
+        if (this.shouldIgnore(rel)) continue;
+        if (ent.isDirectory()) {
+          await walk(full, depth + 1);
+        } else if (AUTHORITY_FILE_MATCHERS.some((m) => m(rel))) {
+          try {
+            const content = await readFile(full, 'utf-8');
+            // C2: skip files whose content exceeds the server's 5MB cap —
+            // manifests are tiny; an oversized one is anomalous.
+            if (content.length > 5_000_000) continue;
+            const hash = createHash('sha256').update(content).digest('hex');
+            out.push({ path: rel, content, hash });
+          } catch {
+            /* unreadable — skip */
+          }
+        }
+      }
+    };
+
+    await walk(projectRoot, 0);
+    return out;
+  }
 }

package/src/hookTimeouts.ts

@@ -0,0 +1,44 @@
+/**
+ * Hook dispatcher HTTP timeout budgets + AbortSignal helper.
+ *
+ * Single source of truth for the timeouts used by the three host-side
+ * hook dispatcher packages (`@mnemonik/claude-code-hooks`,
+ * `@mnemonik/codex-hooks`, `@mnemonik/cursor-hooks`). Before the
+ * 2026-05-16 audit Finding #7 cross-cutting cleanup, each package
+ * declared its own copy of these constants and a near-identical
+ * `withTimeout` helper — coordinating a budget change required three
+ * synchronised edits with no enforcement that the values matched.
+ *
+ * Surface is intentionally minimal: small constants + a single helper
+ * function. No fetch wrappers here — request shaping stays per-package
+ * because each host expresses its hook payloads differently.
+ */
+
+/** Snapshot / file-context / policy-reminder / injections fetch budget. Critical-path. */
+export const FETCH_TIMEOUT_MS = 2000;
+
+/** Telemetry fan-out budget. Drop the metric rather than hold the user. */
+export const TELEMETRY_TIMEOUT_MS = 500;
+
+/** PostToolUse / track-ide-edit budget. Faster than FETCH because it's fire-and-forget. */
+export const POST_TOOL_TIMEOUT_MS = 1500;
+
+/** beforeMCPExecution gate budget. Same as FETCH today; documented separately so it can move independently. */
+export const MCP_PRECHECK_TIMEOUT_MS = 2000;
+
+/**
+ * Spawn an `AbortController` tied to a timeout. Returns the signal plus a
+ * `cleanup` function the caller MUST invoke (in `finally`) to clear the
+ * timer when the request finishes naturally — otherwise the timer leaks
+ * for the timeout duration.
+ *
+ * Identical signature to the inlined `withTimeout` that each hook package
+ * used before this consolidation; call sites swap their local import for
+ * `import { withHookTimeout } from '@mnemonik/shared'` and nothing else
+ * changes.
+ */
+export function withHookTimeout(ms: number): { signal: AbortSignal; cleanup: () => void } {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), ms);
+  return { signal: ac.signal, cleanup: () => clearTimeout(timer) };
+}

package/src/index.ts

@@ -7,7 +7,12 @@
 
 export { MCP_INSTRUCTIONS, MCP_INSTRUCTIONS_RAW, getMcpInstructions } from './instructions.js';
 export { USAGE_GUIDE } from './usageGuide.js';
-export { CodeScanner, type CodeChunk, type ScanOptions } from './codeScanner.js';
+export {
+  CodeScanner,
+  AUTHORITY_FILE_MATCHERS,
+  type CodeChunk,
+  type ScanOptions,
+} from './codeScanner.js';
 export {
   FileSystemReader,
   getFileSystemReader,
@@ -15,3 +20,11 @@ export {
   type ChangedFilesResult,
   type FileData,
 } from './FileSystemReader.js';
+export { SECRET_PATTERNS, SECRET_REDACTION_PLACEHOLDER, scrubSecrets } from './secretPatterns.js';
+export {
+  FETCH_TIMEOUT_MS,
+  TELEMETRY_TIMEOUT_MS,
+  POST_TOOL_TIMEOUT_MS,
+  MCP_PRECHECK_TIMEOUT_MS,
+  withHookTimeout,
+} from './hookTimeouts.js';

package/src/instructions.ts

@@ -4,17 +4,31 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.92
- * Updated: 2026-02-24
+ * Version: 2.98
+ * Updated: 2026-05-27
  *
- * v2.93: Code mode permanent — all memory operations via memory_tools sandbox.
+ * v2.98 — Doc truth contracts are the normal drift surface. linkedDocs and
+ *         doc_code_couplings remain legacy diagnostics only; docs drift
+ *         defaults to truth findings and legacy:true is explicit debug.
+ * v2.97 — Dropped legacy doc-coupling action guidance. Coupling rows are
+ *         not truth findings (plan §1).
+ * v2.96 — Replace conditional memory_discover guidance with structural fix:
+ *         bootstrap now includes _methodCatalog (discoverMemoryTools({})) so
+ *         agents have the memory_tools calling convention from turn one.
+ *         Instruction updated to reference _methodCatalog directly.
+ * v2.95 — Drop `augments` from JIT directive verdict list per plan §5 default
+ *         (augments downgrades to ambient via the parallel recall gate, not
+ *         the directive lane). See jit-knowledge-injector.md §5 decision note.
+ * v2.94 — Add JIT directive teaching (docs/development/jit-knowledge-injector.md §2.3).
+ *
+ * Code mode permanent — all memory operations via memory_tools sandbox.
  *        memory_add, file_context etc. are now mnemonik.* methods, not standalone tools.
  *
- * v2.92: Zero-cooperation rewrite. Context auto-loads if session_bootstrap is skipped.
+ * Zero-cooperation rewrite. Context auto-loads if session_bootstrap is skipped.
  *        Session summaries are auto-saved if agent doesn't call mnemonik.memory_add().
  *        Instructions drastically simplified — the server handles the workflow now.
  *
- * v2.80: Token-optimised rewrite (superseded by v2.92).
+ * Token-optimised rewrite (superseded by later instruction rewrites).
  */
 
 const INSTRUCTIONS_CONTENT = `You have Mnemonik, a persistent memory system for this project.
@@ -22,11 +36,16 @@ const INSTRUCTIONS_CONTENT = `You have Mnemonik, a persistent memory system for
 First call, every session: session_bootstrap. Read the mnemonik skill (from available_skills) for the full workflow.
 After bootstrap: execute _directive.message actions immediately (scanner daemon check is mandatory).
 
+The bootstrap response includes _methodCatalog — the full list of mnemonik methods and the memory_tools calling convention. Read it before making any memory_tools calls. Use memory_discover({ method }) for the full schema and a copy-pasteable example of a specific method or action.
 Proactively call memory_search before starting new work — avoids rediscovering known patterns and contradicting past decisions.
 Proactively call file_context before editing any file — loads past bugs, decisions, and gotchas for that file.
 Proactively call checkpoint after making changes or decisions worth keeping — your context is ephemeral and checkpoint is the only way decisions survive across sessions and context compaction. Do not wait for the user to say "done" or "thanks".
 
-When mnemonik.file_context({ filePaths, cwd }) returns linkedDocs with driftStatus 'stale', update docs then call mnemonik.docs({ action: 'resolve', docPath, cwd }).
+Documentation drift uses explicit doc-truth contracts. Treat _docDrift/docTruthFindings as actionable only when each finding includes a concrete assertion, named authority, observed mismatch, and agentAction='update_doc'. _docHealth, linkedDocs, stale-coupling counts, and docs({ action: 'drift', legacy: true }) are diagnostics only, not instructions to edit or resolve docs.
+
+Ambient envelopes contain background memories surfaced because they may be relevant to your current turn. Treat them as information, not directive. Weight them lower than your own reasoning unless they directly answer the question. They are advisory recall, not authoritative evidence.
+
+Directive envelopes with signal="jit_required" are different from ambient. They surface memories that the server has classified as contradicting or materially refining the answer you were about to give to the current prompt. Each memory carries a verdict (contradicts | refines) and a one-line reason. Treat these as authoritative for the current response — comply with the surfaced fact unless it is clearly outdated or wrong. Do not silently route around them. If you disagree with a surfaced memory, say so explicitly and explain why; do not just ignore it.
 
 Skip: formatting-only, trivial one-line, mechanical refactors, git ops, tests.
 Save: architectural decisions, bug root causes, user preferences, discovered patterns, multi-file changes.`;
@@ -34,9 +53,16 @@ Save: architectural decisions, bug root causes, user preferences, discovered pat
 /**
  * Get MCP instructions, respecting MNEMONIK_INSTRUCTIONS_ENABLED env var.
  * Set MNEMONIK_INSTRUCTIONS_ENABLED=false to disable for testing.
+ *
+ * Reads env through globalThis so this package compiles cleanly without
+ * `@types/node` (shared package's tsconfig doesn't include it, which made
+ * IDEs flag `process` as an unknown global even though the workspace
+ * tsc resolution found it).
  */
 export function getMcpInstructions(): string {
-  if (typeof process !== 'undefined' && process.env?.MNEMONIK_INSTRUCTIONS_ENABLED === 'false') {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process
+    ?.env;
+  if (env?.MNEMONIK_INSTRUCTIONS_ENABLED === 'false') {
     return '';
   }
   return INSTRUCTIONS_CONTENT;

package/src/secretPatterns.ts

@@ -0,0 +1,57 @@
+/**
+ * Single source of truth for secret-redaction patterns.
+ *
+ * Used by:
+ * - packages/shared CodeScanner — scrubs chunk content before computing
+ *   contentHash, so daemon ships scrubbed content (correct hash for
+ *   server-side cache dedup).
+ * - server /api/v1/scan/push handler — re-applies scrub as defense in
+ *   depth (idempotent — already-scrubbed content stays the same), so
+ *   older daemons or compromised daemons can't leak secrets through us.
+ * - server GitMiner — scrubs commit messages before storing as memories.
+ *
+ * Patterns target high-confidence credential shapes:
+ *   1. key=value style: api_key, secret, token, password, credential, auth
+ *   2. Stripe-style sk_live_/pk_test_ keys
+ *   3. GitHub personal access tokens (ghp_ prefix, exact 36 chars)
+ *   4. GitLab personal access tokens (glpat- prefix, 20+ chars)
+ *   5. PEM-style private key headers
+ *
+ * False-positive cost: a few legitimate strings get replaced with the
+ * placeholder. False-negative cost: a credential ships to the server and
+ * gets stored in a memory. The patterns are deliberately tight (require
+ * specific prefixes, length minimums) to keep the false-positive rate low
+ * while catching the common credential leak vectors.
+ */
+
+export const SECRET_REDACTION_PLACEHOLDER = '[REDACTED]';
+
+export const SECRET_PATTERNS: ReadonlyArray<RegExp> = [
+  /(?:api[_-]?key|secret|token|password|credential|auth)\s*[:=]\s*\S+/gi,
+  // Stripe-shape: (sk|pk)_(live|test)_<24+ alphanumerics>. Catches modern
+  // Stripe keys whose body is split by an environment underscore that
+  // breaks the contiguous-alphanum pattern below. Required `live|test`
+  // literal prevents false-positives on snake_case identifiers like
+  // pkg_install_helper_function_xyz_abc_def.
+  /(?:sk|pk)_(?:live|test)_[a-zA-Z0-9]{24,}/g,
+  /(?:sk|pk)[-_][a-zA-Z0-9]{20,}/g,
+  /ghp_[a-zA-Z0-9]{36}/g,
+  /glpat-[a-zA-Z0-9-]{20,}/g,
+  /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/g,
+];
+
+/**
+ * Replace recognized secret shapes in `text` with the redaction
+ * placeholder. Returns the input unchanged when no patterns match.
+ *
+ * Idempotent: scrubbing already-scrubbed text returns the same text
+ * (the placeholder itself doesn't match any pattern).
+ */
+export function scrubSecrets(text: string): string {
+  if (!text) return text;
+  let result = text;
+  for (const pattern of SECRET_PATTERNS) {
+    result = result.replace(pattern, SECRET_REDACTION_PLACEHOLDER);
+  }
+  return result;
+}