@dotdotgod/context 0.2.26 → 0.2.27

package/README.md

@@ -10,7 +10,8 @@ The package exposes a local stdio MCP server and reusable core modules. Claude C
 
 - `execute`, `batch_execute`, `execute_file`
 - `index`, `search`, `fetch_and_index`
-- `stats`, `doctor`, `purge`
+- `session_resume`, `ingestion_job_start`, `ingestion_job_status`, `ingestion_job_cancel`
+- `context_heal`, `stats`, `doctor`, `purge`
 - `dotdotgod_project_load`, `dotdotgod_project_impact`, `dotdotgod_project_initialize`
 
 Run the stdio MCP server directly with:
@@ -46,7 +47,7 @@ Indexed content is stored in the project-local SQLite FTS5 database:
 .dotdotgod/context/context.sqlite
 ```
 
-The store is local ignored state, not maintained project truth. Sources can use transient, session, or project scope and carry optional expiry metadata. Writable connections use WAL and a 1-second busy timeout. Source replacement, expiry, and purge update source and FTS rows transactionally. Existing compatible schemas reopen without migration; incompatible schemas fail before automatic repair. Search applies scope, session, and source predicates before candidate fusion, then:
+The store is local ignored state, not maintained project truth. Sources can use transient, session, or project scope and carry optional expiry metadata. Writable connections use WAL and a 1-second busy timeout. Source replacement, expiry, and purge update source and FTS rows transactionally. Recognized older schemas migrate transactionally through a version ledger; unknown, newer, incomplete, or corrupt schemas fail closed before explicit healing. Search applies scope, session, and source predicates before candidate fusion, then:
 
 1. retrieves bounded Porter-tokenized FTS5 candidates;
 2. retrieves bounded label/path candidates;
@@ -126,6 +127,12 @@ The MCP server also exposes bounded project load, graph impact, and initializer
 
 Claude Code and Codex adapter hooks may tell the model to call these MCP tools and retry a denied operation. Hooks do not transform an ordinary host shell call into an MCP call. Pi retains its native project-memory lifecycle and calls the shared runtime directly.
 
+## Phase 3 Capabilities
+
+Search includes a bounded typo-tolerant trigram lane while Porter FTS remains primary. Databases use transactional version-ledger migrations; explicit healing backs up first and accepts only recognized profiles. Opaque session IDs can be resumed without a history-listing API. Durable background ingestion has bounded queue, status, cancellation, and restart recovery.
+
+Execution keeps compatibility-oriented filtered inheritance by default; this mode is not credential isolation. Opt-in `allowlist-v1` starts from an empty child environment and copies only explicit names, including caller overrides only when separately allowlisted, with names-only reporting. Strict fetch remains default. Browser rendering is available only through an injected renderer plus `browser: true`; this package bundles no browser, keeps rendered content `external-untrusted`, enforces limits/abort, and makes no sandbox claim.
+
 ## Learn More
 
 - [Behavior specification](https://github.com/dotdotgod/dotdotgod-kit/blob/main/docs/spec/CONTEXT_EXECUTION.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/context",
-  "version": "0.2.26",
+  "version": "0.2.27",
   "description": "Local-first MCP execution, indexing, and retrieval runtime for dotdotgod adapters.",
   "type": "module",
   "license": "Elastic-2.0",
@@ -28,7 +28,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
     "zod": "^3.25.76",
-    "@dotdotgod/cli": "0.2.26"
+    "@dotdotgod/cli": "0.2.27"
   },
   "engines": {
     "node": ">=22.5.0"

package/src/content.mjs

@@ -74,9 +74,38 @@ export function indexFile(store, input, sessionId, signal) {
   return indexRegularFile(store, input, sessionId, path, stat);
 }
 
-export async function fetchAndIndex(store, input, sessionId, signal) {
+export async function fetchAndIndex(store, input, sessionId, signal, capabilities = {}) {
   const maxBytes = Math.min(input.maxBytes ?? MAX_FETCH_BYTES, MAX_FETCH_BYTES);
-  const fetched = await safeFetch(input.url, {
+  let fetched;
+  if (input.browser === true) {
+    if (typeof capabilities.renderer !== 'function') throw new Error('Browser rendering capability is unavailable; strict fetch remains the default.');
+    const url = new URL(input.url);
+    if (!['http:', 'https:'].includes(url.protocol)) throw new Error('Only HTTP(S) browser rendering is supported.');
+    const timeoutMs = Math.min(input.timeoutMs ?? 10_000, 120_000);
+    const controller = new AbortController();
+    let rejectAbort;
+    const aborted = new Promise((_, reject) => { rejectAbort = reject; });
+    const abort = () => { const reason = signal?.reason instanceof Error ? signal.reason : new Error('Browser rendering aborted.'); controller.abort(reason); rejectAbort(reason); };
+    if (signal?.aborted) abort(); else signal?.addEventListener('abort', abort, { once: true });
+    let timer;
+    const timeout = new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(new Error('Browser rendering timed out.')); reject(new Error(`Browser rendering timed out after ${timeoutMs}ms.`)); }, timeoutMs); timer.unref?.(); });
+    let rendered;
+    try { rendered = await Promise.race([capabilities.renderer({ url: url.href, signal: controller.signal, timeoutMs, maxBytes }), timeout, aborted]); }
+    finally { clearTimeout(timer); signal?.removeEventListener('abort', abort); }
+    if (!rendered || typeof rendered !== 'object' || Array.isArray(rendered)) throw new Error('Browser renderer returned an invalid result.');
+    if (rendered.body !== undefined && !Buffer.isBuffer(rendered.body)) throw new Error('Browser renderer body must be a Buffer.');
+    if (rendered.text !== undefined && typeof rendered.text !== 'string') throw new Error('Browser renderer text must be a string.');
+    if (rendered.body === undefined && rendered.text === undefined) throw new Error('Browser renderer must return body or text.');
+    const body = rendered.body ?? Buffer.from(rendered.text, 'utf8');
+    if (body.length > maxBytes) throw new Error(`Rendered content exceeds maximum size: ${body.length} bytes`);
+    const finalUrl = String(rendered.url ?? url.href);
+    if (finalUrl.length > 4096 || !['http:', 'https:'].includes(new URL(finalUrl).protocol)) throw new Error('Browser renderer returned an invalid final URL.');
+    const contentType = String(rendered.contentType ?? 'text/html; charset=utf-8');
+    if (contentType.length > 512 || /[\r\n]/u.test(contentType)) throw new Error('Browser renderer returned invalid content type metadata.');
+    const status = rendered.status ?? 200;
+    if (!Number.isInteger(status) || status < 100 || status > 599) throw new Error('Browser renderer returned an invalid HTTP status.');
+    fetched = { body, text: body.toString('utf8'), url: finalUrl, originalUrl: url.href, redirects: [], contentType, contentEncoding: 'identity', status, bytes: body.length, wireLength: body.length };
+  } else fetched = await safeFetch(input.url, {
     signal,
     timeoutMs: input.timeoutMs,
     maxBytes,
@@ -112,6 +141,7 @@ export async function fetchAndIndex(store, input, sessionId, signal) {
         htmlTruncated: normalized.truncated,
         htmlFallbackReason: normalized.fallbackReason,
       } : {}),
+      acquisitionMode: input.browser === true ? 'browser-renderer' : 'strict-fetch',
     },
     provenance: {
       sourceType: 'fetched-url',

package/src/environment-policy.mjs

@@ -34,8 +34,11 @@ function entriesOf(value, label) {
  * Compose a child-process environment without exposing filtered values.
  * Override values may be strings or null; null explicitly deletes a variable.
  */
-export function composeEnvironment({ inherited = {}, overrides = {}, platform = process.platform } = {}) {
+export function composeEnvironment({ inherited = {}, overrides = {}, platform = process.platform, mode = 'inherit-filtered-v1', allow = [] } = {}) {
   const family = platformFamily(platform);
+  if (!['inherit-filtered-v1', 'allowlist-v1'].includes(mode)) throw new TypeError(`Unsupported environment policy mode: ${mode}`);
+  if (!Array.isArray(allow)) throw new TypeError('allow must be an array');
+  const allowed = new Set(allow.map((name) => { validateName(name); return canonicalName(name, family); }));
   const env = {};
   const filtered = new Set();
 
@@ -46,7 +49,7 @@ export function composeEnvironment({ inherited = {}, overrides = {}, platform =
     }
     if (value === undefined) continue;
     const outputName = canonicalName(name, family);
-    if (isFilteredName(outputName, family)) {
+    if (isFilteredName(outputName, family) || (mode === 'allowlist-v1' && !allowed.has(outputName))) {
       filtered.add(outputName);
       continue;
     }
@@ -59,6 +62,7 @@ export function composeEnvironment({ inherited = {}, overrides = {}, platform =
     if (isFilteredName(outputName, family)) {
       throw new TypeError(`Environment variable ${name} is reserved by the execution policy`);
     }
+    if (mode === 'allowlist-v1' && !allowed.has(outputName)) throw new TypeError(`Environment variable ${name} is not in the explicit allowlist`);
     if (value === null) {
       delete env[outputName];
       continue;
@@ -72,8 +76,9 @@ export function composeEnvironment({ inherited = {}, overrides = {}, platform =
   return {
     env,
     policy: {
-      mode: 'inherit-filtered-v1',
+      mode,
       platform: family,
+      ...(mode === 'allowlist-v1' ? { allowedNames: [...allowed].sort((left, right) => left.localeCompare(right, 'en')) } : {}),
       filteredNames: [...filtered].sort((left, right) => left.localeCompare(right, 'en')),
     },
   };

package/src/execute.mjs

@@ -3,6 +3,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawn } from 'node:child_process';
 import { Transform } from 'node:stream';
+import { finished } from 'node:stream/promises';
 import { resolveWithinRoot } from './paths.mjs';
 import { composeEnvironment } from './environment-policy.mjs';
 
@@ -50,6 +51,8 @@ export async function executeCommand(input, options = {}) {
   const environment = composeEnvironment({
     inherited: options.env ?? process.env,
     overrides: input.env ?? {},
+    mode: input.environmentMode ?? 'inherit-filtered-v1',
+    allow: input.allowedEnv ?? [],
   });
 
   try {
@@ -80,14 +83,22 @@ export async function executeCommand(input, options = {}) {
       const timer = setTimeout(() => { timedOut = true; killProcess(child); }, timeoutMs);
       const onAbort = () => { aborted = true; killProcess(child); };
       options.signal?.addEventListener('abort', onAbort, { once: true });
-      child.once('error', (error) => { clearTimeout(timer); reject(error); });
+      let spawnError = false;
+      child.once('error', (error) => {
+        spawnError = true;
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', onAbort);
+        stdout.end(() => stderr.end(() => reject(error)));
+      });
       child.once('close', (code, signal) => {
+        if (spawnError) return;
         clearTimeout(timer);
         options.signal?.removeEventListener('abort', onAbort);
         stdout.end(() => stderr.end(() => resolvePromise({ code, signal })));
       });
     });
 
+    await Promise.all([finished(stdout), finished(stderr)]);
     const outputLimit = Math.min(MAX_DIRECT_RETURN, Math.max(1, input.outputLimit ?? DIRECT_LIMIT));
     const directLimit = Math.min(HARD_LIMIT, Math.max(1, input.directLimit ?? DIRECT_LIMIT));
     const stdoutResult = readBounded(stdoutPath, outputLimit);
@@ -129,13 +140,13 @@ export async function executeCommand(input, options = {}) {
       ...(mode === 'discard' ? {} : shouldIndex ? { indexed } : { stdout: stdoutResult.text, stderr: stderrResult.text, truncated: stdoutResult.truncated || stderrResult.truncated }),
     };
   } finally {
-    rmSync(dir, { recursive: true, force: true });
+    rmSync(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 10 });
   }
 }
 
 export async function executeFile(input, options = {}) {
   const path = resolveWithinRoot(options.root || process.cwd(), input.path);
-  const selectorEnvironment = composeEnvironment({ inherited: options.env ?? process.env, overrides: input.env ?? {} }).env;
+  const selectorEnvironment = composeEnvironment({ inherited: options.env ?? process.env, overrides: input.env ?? {}, mode: input.environmentMode ?? 'inherit-filtered-v1', allow: input.allowedEnv ?? [] }).env;
   const dir = mkdtempSync(join(tmpdir(), 'dotdotgod-context-file-'));
   try {
     let executable;
@@ -158,7 +169,7 @@ export async function executeFile(input, options = {}) {
     }
     return await executeCommand({ ...input, executable, args, command: undefined, shell: false, cwd: input.cwd ?? options.root }, options);
   } finally {
-    rmSync(dir, { recursive: true, force: true });
+    rmSync(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 10 });
   }
 }
 

package/src/index.d.ts

@@ -1,12 +1,15 @@
 export type ContextScope = 'transient' | 'session' | 'project';
 export type DirectoryReason = 'excluded-path' | 'extension-filter' | 'file-byte-limit' | 'file-count-limit' | 'aggregate-byte-limit' | 'visited-entry-limit' | 'depth-limit' | 'file-symlink' | 'directory-symlink' | 'symlink-outside-root' | 'symlink-unresolvable' | 'special-file' | 'directory-read-failed' | 'entry-stat-failed' | 'index-failed';
-export interface EnvironmentPolicy { mode: 'inherit-filtered-v1'; platform: 'win32' | 'darwin' | 'posix'; filteredNames: string[] }
+export interface EnvironmentPolicy { mode: 'inherit-filtered-v1' | 'allowlist-v1'; platform: 'win32' | 'darwin' | 'posix'; allowedNames?: string[]; filteredNames: string[] }
 export interface DirectoryManifestEntry { path: string; absolutePath: string; size: number; identity: { dev: number; ino: number; size: number; mtimeMs: number }; symlink: boolean }
 export interface DirectoryManifest { root: string; directory: string; files: DirectoryManifestEntry[]; skipped: Array<{ path: string; reason: DirectoryReason }>; failed: Array<{ path: string; reason: DirectoryReason; error?: string }>; aborted: boolean; truncated: boolean; visitedEntries: number; aggregateBytes: number }
 export interface HtmlNormalization { text: string; title: string | null; links: Array<{ text: string; href: string }>; extractor: 'html-v1'; fallbackReason: 'malformed-html' | null; mimeType: 'text/html' | 'application/xhtml+xml'; charset: 'utf-8' | 'us-ascii'; inputBytes: number; outputBytes: number; truncated: boolean }
-export interface ExecutionInput { label?: string; command?: string; executable?: string; args?: string[]; shell?: boolean; cwd?: string; timeoutMs?: number; outputLimit?: number; directLimit?: number; outputMode?: 'auto' | 'direct' | 'indexed' | 'discard'; scope?: ContextScope; ttlMs?: number; env?: Record<string, string | null> }
+export interface ExecutionInput { label?: string; command?: string; executable?: string; args?: string[]; shell?: boolean; cwd?: string; timeoutMs?: number; outputLimit?: number; directLimit?: number; outputMode?: 'auto' | 'direct' | 'indexed' | 'discard'; scope?: ContextScope; ttlMs?: number; env?: Record<string, string | null>; environmentMode?: 'inherit-filtered-v1' | 'allowlist-v1'; allowedEnv?: string[] }
 export interface IndexInput { path: string; root?: string; source?: string; scope?: ContextScope; ttlMs?: number; maxBytes?: number; includeExtensions?: string[]; excludePaths?: string[]; followFileSymlinks?: boolean; maxDepth?: number; maxVisitedEntries?: number; maxFiles?: number; maxAggregateBytes?: number }
-export interface FetchInput { url: string; source?: string; scope?: ContextScope; ttlMs?: number; timeoutMs?: number; maxBytes?: number }
+export interface FetchInput { url: string; source?: string; scope?: ContextScope; ttlMs?: number; timeoutMs?: number; maxBytes?: number; browser?: boolean }
+export interface IndexResult { id: string; chunks: number; bytes: number; scope: ContextScope; expiresAt: number | null }
+export interface FetchResult extends IndexResult {}
+export interface IngestionJob { id: string; state: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled'; kind: 'index' | 'fetch'; input: Record<string, unknown>; sessionId: string | null; result: unknown; error: string | null; createdAt: number; updatedAt: number }
 export interface DoctorResult { ok: boolean; status: 'OK' | 'WARN' | 'FAIL'; node: string; platform: string; root: string; dbPath: string; checks: Array<{ id: string; status: 'OK' | 'WARN' | 'FAIL'; message: string; details?: unknown }> }
 
 export function contextDbPath(root?: string): string;
@@ -19,13 +22,27 @@ export class ContextStore {
   search(input: { query: string; scope?: ContextScope; sessionId?: string; source?: string; limit?: number }): unknown[];
   stats(): { path: string; sources: number; chunks: number; byScope: Array<{ scope: ContextScope; count: number }> };
   purge(input: { scope?: ContextScope; sessionId?: string; sourceId?: string }): { removed: number };
+  createJob(input: { id?: string; kind: 'index' | 'fetch'; input: Record<string, unknown>; sessionId?: string | null }): IngestionJob;
+  getJob(id: string): IngestionJob | null;
+  claimNextJob(): IngestionJob | null;
+  finishJob(id: string, state: 'completed' | 'failed' | 'cancelled', value?: unknown): IngestionJob | null;
+  cancelJob(id: string): { changed: number; job: IngestionJob | null };
+  listPendingJobs(limit?: number): IngestionJob[];
 }
+export function healContextDatabase(root?: string): { ok: true; backupPath: string; fromVersion: number; toVersion: number; rebuilt: true };
+export function validateSessionId(value: unknown): string;
+export function resolveSessionId(value?: unknown): string;
+export class IngestionJobRunner { sessionId?: string; constructor(store: ContextStore, options?: { sessionId?: string; renderer?: BrowserRenderer; root?: string }); enqueue(kind: 'index' | 'fetch', input: Record<string, unknown>): IngestionJob; status(id: string): IngestionJob | null; cancel(id: string): { changed: number; job: IngestionJob | null }; pump(): Promise<void> }
+export interface BrowserRendererResult { body?: Buffer; text?: string; url?: string; contentType?: string; status?: number }
+export type BrowserRenderer = (input: Readonly<{ url: string; signal: AbortSignal; timeoutMs: number; maxBytes: number }>) => Promise<BrowserRendererResult>;
+export const INGESTION_JOB_LIMITS: Readonly<{ maxPendingJobs: number; concurrency: 1 }>;
+export const PHASE3_TOOL_INPUT_SCHEMAS: Readonly<Record<'session_resume' | 'ingestion_job_start' | 'ingestion_job_status' | 'ingestion_job_cancel' | 'context_heal', Readonly<Record<string, unknown>>>>;
 export function executeCommand(input: ExecutionInput, options?: { root?: string; store?: ContextStore; sessionId?: string; signal?: AbortSignal | undefined; env?: Record<string, string | undefined>; captureLimitBytes?: number }): Promise<Record<string, any>>;
 export function executeBatch(input: { commands: ExecutionInput[]; concurrency?: number; cwd?: string; timeoutMs?: number }, options?: Record<string, any>): Promise<Record<string, any>>;
 export function executeFile(input: ExecutionInput & { path: string; language: 'javascript' | 'python' | 'shell'; code: string }, options?: Record<string, any>): Promise<Record<string, any>>;
-export function indexFile(store: ContextStore, input: IndexInput, sessionId?: string, signal?: AbortSignal): Record<string, any>;
-export function fetchAndIndex(store: ContextStore, input: FetchInput, sessionId?: string, signal?: AbortSignal): Promise<Record<string, any>>;
-export function composeEnvironment(input?: { inherited?: Record<string, string | undefined>; overrides?: Record<string, string | null>; platform?: string }): { env: Record<string, string>; policy: EnvironmentPolicy };
+export function indexFile(store: ContextStore, input: IndexInput, sessionId?: string, signal?: AbortSignal): IndexResult | (Record<string, unknown> & { indexed: IndexResult[] });
+export function fetchAndIndex(store: ContextStore, input: FetchInput, sessionId?: string, signal?: AbortSignal, capabilities?: { renderer?: BrowserRenderer }): Promise<FetchResult>;
+export function composeEnvironment(input?: { inherited?: Record<string, string | undefined>; overrides?: Record<string, string | null>; platform?: string; mode?: 'inherit-filtered-v1' | 'allowlist-v1'; allow?: string[] }): { env: Record<string, string>; policy: EnvironmentPolicy };
 export const DIRECTORY_INGESTION_LIMITS: Readonly<{ maxDepth: number; maxVisitedEntries: number; maxFiles: number; maxFileBytes: number; maxAggregateBytes: number }>;
 export function walkDirectoryManifest(input: IndexInput & { signal?: AbortSignal }): DirectoryManifest;
 export function verifyManifestFile(entry: DirectoryManifestEntry, root: string): string;

package/src/index.mjs

@@ -1,8 +1,11 @@
 export { chunkContent, chunkJson, chunkMarkdown, chunkText, excerpt, normalizeText } from './chunks.mjs';
-export { ContextStore, contextDbPath } from './store.mjs';
+export { ContextStore, contextDbPath, healContextDatabase } from './store.mjs';
 export { executeBatch, executeCommand, executeFile } from './execute.mjs';
 export { fetchAndIndex, indexFile } from './content.mjs';
 export { composeEnvironment } from './environment-policy.mjs';
+export { INGESTION_JOB_LIMITS, IngestionJobRunner } from './jobs.mjs';
+export { resolveSessionId, validateSessionId } from './session.mjs';
+export { PHASE3_TOOL_INPUT_SCHEMAS } from './tool-contracts.mjs';
 export { DIRECTORY_INGESTION_LIMITS, readManifestFile, verifyManifestFile, walkDirectoryManifest } from './directory-ingestion.mjs';
 export { normalizeHtml } from './html-normalize.mjs';
 export { runDoctor } from './doctor.mjs';

package/src/jobs.mjs

@@ -0,0 +1,62 @@
+import { fetchAndIndex, indexFile } from './content.mjs';
+
+const MAX_PENDING_JOBS = 100;
+
+export class IngestionJobRunner {
+  constructor(store, { sessionId, renderer, root } = {}) {
+    this.store = store;
+    this.sessionId = sessionId;
+    this.root = root ?? store.root;
+    this.renderer = renderer;
+    this.running = false;
+    this.scheduled = false;
+    this.controllers = new Map();
+    this.schedule();
+  }
+
+  enqueue(kind, input) {
+    if (!['index', 'fetch'].includes(kind)) throw new Error('Unsupported ingestion job kind.');
+    const job = this.store.createJob({ kind, input, sessionId: this.sessionId ?? null });
+    this.schedule();
+    return job;
+  }
+
+  status(id) { return this.store.getJob(id); }
+
+  cancel(id) {
+    this.controllers.get(id)?.abort();
+    return this.store.cancelJob(id);
+  }
+
+  schedule() {
+    if (this.scheduled || this.running) return;
+    this.scheduled = true;
+    queueMicrotask(() => { this.scheduled = false; void this.pump(); });
+  }
+
+  async pump() {
+    if (this.running) return;
+    this.running = true;
+    try {
+      for (;;) {
+        const job = this.store.claimNextJob();
+        if (!job) break;
+        const controller = new AbortController();
+        this.controllers.set(job.id, controller);
+        try {
+          const value = job.kind === 'index'
+            ? indexFile(this.store, { ...job.input, root: this.root }, job.sessionId ?? undefined, controller.signal)
+            : await fetchAndIndex(this.store, job.input, job.sessionId ?? undefined, controller.signal, { renderer: this.renderer });
+          const current = this.store.getJob(job.id);
+          if (current?.state === 'running') this.store.finishJob(job.id, 'completed', value);
+        } catch (error) {
+          const current = this.store.getJob(job.id);
+          if (current?.state === 'running') this.store.finishJob(job.id, controller.signal.aborted ? 'cancelled' : 'failed', error instanceof Error ? error.message : String(error));
+        } finally { this.controllers.delete(job.id); }
+        await new Promise((resolve) => setImmediate(resolve));
+      }
+    } finally { this.running = false; }
+  }
+}
+
+export const INGESTION_JOB_LIMITS = Object.freeze({ maxPendingJobs: MAX_PENDING_JOBS, concurrency: 1 });

package/src/server.mjs

@@ -1,21 +1,26 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { ContextStore, contextDbPath } from './store.mjs';
+import { ContextStore, contextDbPath, healContextDatabase } from './store.mjs';
 import { executeBatch, executeCommand, executeFile } from './execute.mjs';
 import { fetchAndIndex, indexFile } from './content.mjs';
 import { runDoctor } from './doctor.mjs';
 import { projectImpact, projectInitialize, projectLoad } from './project.mjs';
 import { resolveWithinRoot } from './paths.mjs';
+import { IngestionJobRunner } from './jobs.mjs';
+import { resolveSessionId, validateSessionId } from './session.mjs';
+import { PHASE3_TOOL_INPUT_SCHEMAS } from './tool-contracts.mjs';
 
 const root = process.env.DOTDOTGOD_PROJECT_ROOT || process.cwd();
-const sessionId = process.env.DOTDOTGOD_SESSION_ID || crypto.randomUUID();
+let sessionId = resolveSessionId(process.env.DOTDOTGOD_SESSION_ID);
 let contextStore;
+let jobRunner;
 function getStore() {
   contextStore ??= new ContextStore(root);
   return contextStore;
 }
-const server = new McpServer({ name: 'dotdotgod-context', version: '0.2.26' });
+function getJobs() { jobRunner ??= new IngestionJobRunner(getStore(), { sessionId }); return jobRunner; }
+const server = new McpServer({ name: 'dotdotgod-context', version: '0.2.27' });
 
 const scopeSchema = z.enum(['transient', 'session', 'project']).optional();
 const outputModeSchema = z.enum(['auto', 'direct', 'indexed', 'discard']).optional();
@@ -23,7 +28,7 @@ const commandSchema = {
   label: z.string().optional(), command: z.string().optional(), executable: z.string().optional(), args: z.array(z.string()).optional(),
   shell: z.boolean().optional(), cwd: z.string().optional(), timeoutMs: z.number().int().positive().optional(), outputLimit: z.number().int().positive().optional(),
   directLimit: z.number().int().positive().optional(), outputMode: outputModeSchema, scope: scopeSchema, ttlMs: z.number().int().nonnegative().optional(),
-  env: z.record(z.string(), z.string().nullable()).optional(),
+  env: z.record(z.string(), z.string().nullable()).optional(), environmentMode: z.enum(['inherit-filtered-v1', 'allowlist-v1']).optional(), allowedEnv: z.array(z.string()).max(100).optional(),
 };
 
 function success(value) {
@@ -63,8 +68,32 @@ register('search', 'Search indexed command, file, and fetched content and return
   results: getStore().search({ ...input, sessionId: input.sessionOnly ? sessionId : undefined }),
 }), { readOnlyHint: true });
 register('fetch_and_index', 'Fetch an HTTP(S) URL locally, index bounded text, and return metadata only.', {
-  url: z.string().url(), source: z.string().optional(), scope: scopeSchema, ttlMs: z.number().int().nonnegative().optional(), timeoutMs: z.number().int().positive().optional(), maxBytes: z.number().int().positive().optional(),
+  url: z.string().url(), source: z.string().optional(), scope: scopeSchema, ttlMs: z.number().int().nonnegative().optional(), timeoutMs: z.number().int().positive().optional(), maxBytes: z.number().int().positive().optional(), browser: z.boolean().optional(),
 }, (input, extra) => fetchAndIndex(getStore(), input, sessionId, extra.signal).then((value) => ({ ok: true, ...value })), { openWorldHint: true, readOnlyHint: true });
+function zodFromContract(schema) {
+  if (schema.const !== undefined) return z.literal(schema.const);
+  if (schema.enum) return z.enum(schema.enum);
+  if (schema.type === 'string') {
+    let value = z.string();
+    if (schema.minLength !== undefined) value = value.min(schema.minLength);
+    if (schema.maxLength !== undefined) value = value.max(schema.maxLength);
+    if (schema.pattern) value = value.regex(new RegExp(schema.pattern, 'u'));
+    if (schema.format === 'uuid') value = value.uuid();
+    return value;
+  }
+  if (schema.type === 'object') {
+    if (!schema.properties) return z.record(z.string(), z.unknown());
+    const required = new Set(schema.required ?? []);
+    return z.object(Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => [key, required.has(key) ? zodFromContract(value) : zodFromContract(value).optional()]))).strict();
+  }
+  throw new Error('Unsupported shared tool contract schema.');
+}
+const phase3Shape = (name) => zodFromContract(PHASE3_TOOL_INPUT_SCHEMAS[name]).shape;
+register('session_resume', 'Use an explicit opaque session ID for subsequent context operations; historical sessions are not listed.', phase3Shape('session_resume'), (input) => { sessionId = validateSessionId(input.sessionId); if (jobRunner) jobRunner.sessionId = sessionId; return { ok: true, sessionId }; });
+register('ingestion_job_start', 'Queue one durable bounded background index or strict-fetch ingestion job.', phase3Shape('ingestion_job_start'), (input) => ({ ok: true, job: getJobs().enqueue(input.kind, input.input) }));
+register('ingestion_job_status', 'Return bounded status for one background ingestion job.', phase3Shape('ingestion_job_status'), (input) => ({ ok: true, job: getJobs().status(input.id) }), { readOnlyHint: true });
+register('ingestion_job_cancel', 'Cancel one queued or running background ingestion job.', phase3Shape('ingestion_job_cancel'), (input) => ({ ok: true, ...getJobs().cancel(input.id) }), { destructiveHint: true });
+register('context_heal', 'Explicitly back up and migrate only a recognized recoverable context database.', phase3Shape('context_heal'), () => { contextStore?.close(); contextStore = undefined; jobRunner = undefined; return healContextDatabase(root); }, { destructiveHint: true });
 register('stats', 'Report local context store counts and location.', {}, () => ({ ok: true, sessionId, ...getStore().stats() }), { readOnlyHint: true });
 register('doctor', 'Run local read-only Node.js, SQLite FTS5, storage, schema, and fetch-policy checks without network or repair actions.', {}, () => ({ sessionId, ...runDoctor({ root, dbPath: contextDbPath(root) }) }), { readOnlyHint: true });
 register('purge', 'Permanently delete one explicit context scope, session, or source.', {

package/src/session.mjs

@@ -0,0 +1,12 @@
+const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
+
+export function validateSessionId(value) {
+  if (typeof value !== 'string' || !SESSION_ID.test(value)) {
+    throw new TypeError('sessionId must be an opaque 1-128 character identifier using letters, digits, dot, underscore, tilde, or hyphen.');
+  }
+  return value;
+}
+
+export function resolveSessionId(value) {
+  return value == null ? crypto.randomUUID() : validateSessionId(value);
+}

package/src/store.mjs

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, rmSync, statSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { extname } from 'node:path';
@@ -20,6 +20,9 @@ export function contextDbPath(root) {
   return join(safeRoot(root), '.dotdotgod', 'context', 'context.sqlite');
 }
 
+const SCHEMA_VERSION = 3;
+const MAX_PENDING_JOBS = 100;
+
 function inspectSchema(db) {
   const objects = new Map(db.prepare("SELECT name, type, sql FROM sqlite_master WHERE name IN ('sources', 'chunks')").all().map((row) => [row.name, row]));
   const sourceRows = db.prepare('PRAGMA table_info(sources)').all();
@@ -41,7 +44,102 @@ function inspectSchema(db) {
     && chunkShape
     && missingSources.length === 0
     && missingChunks.length === 0;
-  return { compatible, schemaProfile: compatible ? 1 : null, missing: [...missingSources, ...missingChunks] };
+  let version = 0;
+  if (compatible) {
+    const ledger = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'").get();
+    if (ledger) version = Number(db.prepare('SELECT coalesce(max(version), 0) AS version FROM schema_migrations').get().version);
+    else version = 1;
+  }
+  return { compatible: compatible && version <= SCHEMA_VERSION, schemaProfile: compatible ? version : null, missing: [...missingSources, ...missingChunks] };
+}
+
+function migrate(db, fromVersion) {
+  if (fromVersion > SCHEMA_VERSION) throw new Error(`Incompatible context database schema version ${fromVersion}; runtime supports ${SCHEMA_VERSION}.`);
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    db.exec('CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY, applied_at INTEGER NOT NULL);');
+    if (fromVersion < 2) {
+      db.exec(`CREATE TABLE IF NOT EXISTS ingestion_jobs (
+        id TEXT PRIMARY KEY, state TEXT NOT NULL CHECK(state IN ('queued','running','completed','failed','cancelled')),
+        kind TEXT NOT NULL, input TEXT NOT NULL, result TEXT, error TEXT,
+        created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+      ); CREATE INDEX IF NOT EXISTS ingestion_jobs_state_created ON ingestion_jobs(state, created_at);`);
+      db.prepare('INSERT OR IGNORE INTO schema_migrations(version, applied_at) VALUES (1, ?)').run(Date.now());
+      db.prepare('INSERT OR IGNORE INTO schema_migrations(version, applied_at) VALUES (2, ?)').run(Date.now());
+    }
+    if (fromVersion < 3) {
+      const columns = db.prepare('PRAGMA table_info(ingestion_jobs)').all();
+      if (!columns.some((row) => row.name === 'session_id')) db.exec('ALTER TABLE ingestion_jobs ADD COLUMN session_id TEXT;');
+      db.prepare('INSERT OR IGNORE INTO schema_migrations(version, applied_at) VALUES (3, ?)').run(Date.now());
+    }
+    db.exec('COMMIT');
+  } catch (error) { db.exec('ROLLBACK'); throw error; }
+}
+
+function trigrams(value) {
+  const normalized = `  ${String(value).toLocaleLowerCase('en').replace(/[^\p{L}\p{N}]+/gu, ' ').trim()}  `;
+  const out = new Set();
+  for (let index = 0; index + 3 <= normalized.length; index += 1) out.add(normalized.slice(index, index + 3));
+  return out;
+}
+function trigramScore(left, right) {
+  const a = trigrams(left); const b = trigrams(right);
+  if (!a.size || !b.size) return 0;
+  let overlap = 0; for (const item of a) if (b.has(item)) overlap += 1;
+  return (2 * overlap) / (a.size + b.size);
+}
+function editDistance(left, right, ceiling = 2) {
+  if (Math.abs(left.length - right.length) > ceiling) return ceiling + 1;
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= left.length; i += 1) {
+    const current = [i]; let rowMin = i;
+    for (let j = 1; j <= right.length; j += 1) { current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + (left[i - 1] === right[j - 1] ? 0 : 1)); rowMin = Math.min(rowMin, current[j]); }
+    if (rowMin > ceiling) return ceiling + 1; previous = current;
+  }
+  return previous[right.length];
+}
+function typoScore(query, value) {
+  const queryTerms = normalizeSearchTerms(query);
+  const valueTerms = normalizeSearchTerms(value);
+  let best = 0;
+  for (const needle of queryTerms) for (const token of valueTerms) {
+    if (needle.length >= 5 && editDistance(needle, token) <= 2) best = Math.max(best, trigramScore(needle, token));
+  }
+  return best;
+}
+
+export function healContextDatabase(root = process.cwd()) {
+  const path = contextDbPath(root);
+  if (!existsSync(path)) throw new Error('No context database exists to heal.');
+  const stamp = Date.now();
+  const backupPath = `${path}.backup-${stamp}`;
+  const rebuiltPath = `${path}.healed-${stamp}`;
+  let inspection;
+  let replaced = false;
+  const db = new DatabaseSync(path);
+  try {
+    db.exec('PRAGMA busy_timeout=1000; PRAGMA wal_checkpoint(FULL);');
+    inspection = inspectSchema(db);
+    if (!inspection.compatible || ![1, 2, 3].includes(inspection.schemaProfile)) {
+      throw new Error('Schema is not a recognized recoverable context database; no rebuild performed.');
+    }
+    copyFileSync(path, backupPath, 0);
+    migrate(db, inspection.schemaProfile);
+    db.exec('PRAGMA wal_checkpoint(TRUNCATE);');
+    db.exec(`VACUUM INTO '${rebuiltPath.replaceAll("'", "''")}';`);
+  } catch (error) {
+    rmSync(rebuiltPath, { force: true });
+    throw error;
+  } finally { db.close(); }
+  try {
+    renameSync(rebuiltPath, path);
+    replaced = true;
+    rmSync(`${path}-wal`, { force: true });
+    rmSync(`${path}-shm`, { force: true });
+  } finally {
+    if (!replaced) rmSync(rebuiltPath, { force: true });
+  }
+  return { ok: true, backupPath, fromVersion: inspection.schemaProfile, toVersion: SCHEMA_VERSION, rebuilt: true };
 }
 
 export class ContextStore {
@@ -49,12 +147,14 @@ export class ContextStore {
     this.root = safeRoot(root);
     this.path = contextDbPath(this.root);
     const existing = existsSync(this.path);
+    let schemaVersion = 1;
     if (existing) {
       if (statSync(this.path).size === 0) throw new Error('Incompatible context database schema; empty database cannot be repaired automatically.');
       const inspection = new DatabaseSync(this.path, { readOnly: true });
       try {
         const result = inspectSchema(inspection);
-        if (!result.compatible) throw new Error(`Incompatible context database schema; run doctor before repair${result.missing.length ? ` (missing: ${result.missing.join(', ')})` : ''}.`);
+        if (!result.compatible) throw new Error(`Incompatible context database schema; run doctor before explicit healing${result.missing.length ? ` (missing: ${result.missing.join(', ')})` : ''}.`);
+        schemaVersion = result.schemaProfile;
       } finally {
         inspection.close();
       }
@@ -83,6 +183,8 @@ export class ContextStore {
           tokenize='porter unicode61'
         );
       `);
+      migrate(this.db, schemaVersion);
+      this.db.prepare("UPDATE ingestion_jobs SET state = 'queued', updated_at = ? WHERE state = 'running'").run(Date.now());
     } catch (error) {
       this.db.close();
       throw error;
@@ -161,6 +263,27 @@ export class ContextStore {
         AND (${labelClauses.join(' OR ')})${filterSql}
       ORDER BY lower(s.label), c.ordinal LIMIT ?
     `).all(...labelParams, ...filterParams, candidateLimit);
+    const typoWindow = Math.min(500, candidateLimit * 5);
+    const typoHalf = Math.max(1, Math.floor(typoWindow / 2));
+    const trigramRows = this.db.prepare(`
+      SELECT * FROM (
+        SELECT ${select.replace('SELECT ', '')}, 0 AS rank
+        FROM chunks c JOIN sources s ON s.id = c.source_id
+        WHERE 1 = 1${filterSql}
+        ORDER BY c.rowid ASC LIMIT ?
+      )
+      UNION ALL
+      SELECT * FROM (
+        SELECT ${select.replace('SELECT ', '')}, 0 AS rank
+        FROM chunks c JOIN sources s ON s.id = c.source_id
+        WHERE 1 = 1${filterSql}
+        ORDER BY c.rowid DESC LIMIT ?
+      )
+    `).all(...filterParams, typoHalf, ...filterParams, typoWindow - typoHalf)
+      .map((row) => ({ ...row, trigramScore: Math.max(typoScore(query, row.body), Number(row.ordinal) === 0 ? typoScore(query, row.label) : 0) }))
+      .filter((row) => row.trigramScore >= 0.5)
+      .sort((left, right) => right.trigramScore - left.trigramScore || String(left.source_id).localeCompare(String(right.source_id), 'en') || Number(left.ordinal) - Number(right.ordinal))
+      .slice(0, candidateLimit);
     const toCandidate = (row) => {
       let storedMetadata = {};
       try { storedMetadata = JSON.parse(row.metadata); } catch { /* legacy invalid metadata */ }
@@ -169,6 +292,7 @@ export class ContextStore {
     const fused = reciprocalRankFusion([
       { name: 'porter-bm25', candidates: porterRows.map(toCandidate) },
       { name: 'label-path', candidates: labelRows.map(toCandidate) },
+      { name: 'trigram-v1', candidates: trigramRows.map(toCandidate) },
     ], { limit: candidateLimit });
     return rerankCandidates(fused, query, { limit: resultLimit }).map((entry) => {
       const row = entry.candidate;
@@ -190,6 +314,53 @@ export class ContextStore {
     });
   }
 
+  createJob({ id = crypto.randomUUID(), kind, input, sessionId = null }) {
+    const now = Date.now();
+    const serializedInput = JSON.stringify(input);
+    if (Buffer.byteLength(serializedInput) > 64 * 1024) throw new Error('Background ingestion job input exceeds 64 KiB.');
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const pending = Number(this.db.prepare("SELECT count(*) AS count FROM ingestion_jobs WHERE state IN ('queued','running')").get().count);
+      if (pending >= MAX_PENDING_JOBS) throw new Error('Background ingestion queue is full.');
+      this.db.prepare('INSERT INTO ingestion_jobs(id, state, kind, input, session_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)')
+        .run(id, 'queued', kind, serializedInput, sessionId, now, now);
+      this.db.exec('COMMIT');
+    } catch (error) { this.db.exec('ROLLBACK'); throw error; }
+    return this.getJob(id);
+  }
+
+  getJob(id) {
+    const row = this.db.prepare('SELECT * FROM ingestion_jobs WHERE id = ?').get(id);
+    if (!row) return null;
+    return { id: row.id, state: row.state, kind: row.kind, input: JSON.parse(row.input), sessionId: row.session_id ?? null, result: row.result ? JSON.parse(row.result) : null, error: row.error, createdAt: row.created_at, updatedAt: row.updated_at };
+  }
+
+  claimNextJob() {
+    const row = this.db.prepare("SELECT id FROM ingestion_jobs WHERE state = 'queued' ORDER BY created_at, id LIMIT 1").get();
+    if (!row) return null;
+    const changed = this.db.prepare("UPDATE ingestion_jobs SET state = 'running', updated_at = ? WHERE id = ? AND state = 'queued'").run(Date.now(), row.id).changes;
+    return changed ? this.getJob(row.id) : null;
+  }
+
+  finishJob(id, state, value = null) {
+    if (!['completed', 'failed', 'cancelled'].includes(state)) throw new Error('Invalid terminal job state.');
+    let result = state === 'completed' ? JSON.stringify(value) : null;
+    if (result && Buffer.byteLength(result) > 256 * 1024) result = JSON.stringify({ truncated: true, message: 'Completed result exceeded the durable status limit.' });
+    const error = state === 'failed' ? String(value ?? 'Job failed').slice(0, 4096) : null;
+    this.db.prepare("UPDATE ingestion_jobs SET state = ?, result = ?, error = ?, updated_at = ? WHERE id = ? AND state IN ('queued','running')")
+      .run(state, result, error, Date.now(), id);
+    return this.getJob(id);
+  }
+
+  cancelJob(id) {
+    const changed = this.db.prepare("UPDATE ingestion_jobs SET state = 'cancelled', updated_at = ? WHERE id = ? AND state IN ('queued','running')").run(Date.now(), id).changes;
+    return { changed: Number(changed), job: this.getJob(id) };
+  }
+
+  listPendingJobs(limit = 20) {
+    return this.db.prepare("SELECT id FROM ingestion_jobs WHERE state IN ('queued','running') ORDER BY created_at, id LIMIT ?").all(Math.min(100, Math.max(1, limit))).map((row) => this.getJob(row.id));
+  }
+
   stats() {
     this.expire();
     const sources = this.db.prepare('SELECT count(*) AS count FROM sources').get().count;

package/src/tool-contracts.mjs

@@ -0,0 +1,13 @@
+const object = (properties, required = []) => Object.freeze({ type: 'object', properties, required, additionalProperties: false, $schema: 'http://json-schema.org/draft-07/schema#' });
+const string = (options = {}) => Object.freeze({ type: 'string', ...options });
+
+export const PHASE3_TOOL_INPUT_SCHEMAS = Object.freeze({
+  session_resume: object({ sessionId: string({ minLength: 1, maxLength: 128, pattern: '^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$' }) }, ['sessionId']),
+  ingestion_job_start: object({
+    kind: Object.freeze({ type: 'string', enum: ['index', 'fetch'] }),
+    input: Object.freeze({ type: 'object', additionalProperties: Object.freeze({}) }),
+  }, ['kind', 'input']),
+  ingestion_job_status: object({ id: string({ format: 'uuid' }) }, ['id']),
+  ingestion_job_cancel: object({ id: string({ format: 'uuid' }) }, ['id']),
+  context_heal: object({ confirm: Object.freeze({ const: true, type: 'boolean' }) }, ['confirm']),
+});