vibe-splain 3.1.0 → 3.2.1

package/dist/index.js

@@ -1201,10 +1201,10 @@ async function discoverAllTsConfigs(dir, projectRoot, maxDepth = 4) {
   const result = {};
   if (maxDepth < 0)
     return result;
-  const { readdir: readdir2 } = await import("fs/promises");
+  const { readdir: readdir3 } = await import("fs/promises");
   let entries = [];
   try {
-    entries = await readdir2(dir, { withFileTypes: true });
+    entries = await readdir3(dir, { withFileTypes: true });
   } catch {
     return result;
   }
@@ -1284,10 +1284,10 @@ async function discoverWorkspacePackages(projectRoot) {
     const absPrefix = join3(projectRoot, prefix);
     if (!existsSync3(absPrefix))
       continue;
-    const { readdir: readdir2 } = await import("fs/promises");
+    const { readdir: readdir3 } = await import("fs/promises");
     let entries = [];
     try {
-      const dirents = await readdir2(absPrefix, { withFileTypes: true });
+      const dirents = await readdir3(absPrefix, { withFileTypes: true });
       entries = dirents.filter((d) => d.isDirectory()).map((d) => d.name);
     } catch {
       continue;
@@ -3210,10 +3210,93 @@ var RecommendationEngine = class {
   }
 };
 
+// ../brain/dist/ProofValidator.js
+import { createHash } from "crypto";
+import { readFile as readFile9 } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+var ProofValidator = class {
+  /**
+   * Full validation of a WorkerReceipt against a Work Order's required proofs.
+   * Checks all 8 required conditions from the spec.
+   *
+   * @param receipt - The WorkerReceipt to validate
+   * @param requiredProof - Proof descriptors from the Work Order
+   * @param isAllowedFile - Predicate built by the CLI layer (handles globs/allowedFiles)
+   * @param blobDir - Path to .vibe-splainer/blobs/
+   */
+  static async validate(receipt, requiredProof, isAllowedFile, blobDir) {
+    const errors = [];
+    const warnings = [];
+    for (const req of requiredProof) {
+      const found = receipt.proofPointers.find((p) => p.schemaName === req.schemaName || p.pointer.includes(req.proofId));
+      if (!found) {
+        errors.push(`MissingProof: required proof "${req.proofId}" (schema: ${req.schemaName}) not in receipt`);
+      }
+    }
+    for (const proof of receipt.proofPointers) {
+      const blobPath = resolveBlobPath(blobDir, proof.contentHash);
+      if (!existsSync4(blobPath)) {
+        errors.push(`UnresolvablePointer: blob not found for pointer ${proof.pointer} (hash: ${proof.contentHash})`);
+        continue;
+      }
+      const actualHash = await hashBlob(blobPath);
+      if (actualHash !== proof.contentHash) {
+        errors.push(`HashMismatch: proof ${proof.pointer} expected ${proof.contentHash}, got ${actualHash}`);
+        continue;
+      }
+      const reqDescriptor = requiredProof.find((r) => r.schemaName === proof.schemaName);
+      if (!reqDescriptor) {
+        warnings.push(`UnknownSchema: proof ${proof.pointer} has schema "${proof.schemaName}" not listed in requiredProof`);
+      }
+      if (proof.schemaName.startsWith("test_report")) {
+        try {
+          const blobContent = await readFile9(blobPath, "utf8");
+          const report = JSON.parse(blobContent);
+          if (report.status !== "pass" && report.passed !== true && report.success !== true) {
+            errors.push(`TestFailed: proof ${proof.pointer} (schema: ${proof.schemaName}) reports status "${report.status ?? "unknown"}"`);
+          }
+        } catch {
+          errors.push(`UnreadableProof: cannot parse proof blob for ${proof.pointer}`);
+        }
+      }
+    }
+    for (const changed of receipt.changedFiles) {
+      if (!isAllowedFile(changed.path)) {
+        errors.push(`ScopeViolation: patch touched out-of-scope file "${changed.path}"`);
+      }
+    }
+    for (const changed of receipt.changedFiles) {
+      if (!changed.prePatchHash.startsWith("sha256:") && changed.prePatchHash !== "sha256:new") {
+        errors.push(`InvalidHash: prePatchHash for ${changed.path} is not sha256 format`);
+      }
+      if (!changed.postPatchHash.startsWith("sha256:")) {
+        errors.push(`InvalidHash: postPatchHash for ${changed.path} is not sha256 format`);
+      }
+      const matchingPatch = receipt.proofPointers.find((p) => p.schemaName === "patch_hash" && p.contentHash === changed.postPatchHash);
+      if (!matchingPatch) {
+        warnings.push(`NoMatchingPatchProof: no patch_hash proof matches postPatchHash for ${changed.path}`);
+      }
+    }
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+};
+function resolveBlobPath(blobDir, contentHash) {
+  const hex = contentHash.replace("sha256:", "");
+  return `${blobDir}/sha256_${hex}`;
+}
+async function hashBlob(blobPath) {
+  const buf = await readFile9(blobPath);
+  return `sha256:${createHash("sha256").update(buf).digest("hex")}`;
+}
+
 // dist/export/ArtifactBundleWriter.js
 import { join as join10 } from "path";
 import { writeFile as writeFile7, mkdir as mkdir6, rm, rename } from "fs/promises";
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 var ArtifactBundleWriter = class {
   projectRoot;
   constructor(projectRoot) {
@@ -3226,9 +3309,9 @@ var ArtifactBundleWriter = class {
     try {
       await rm(stagingDir, { recursive: true, force: true });
       await rm(oldDir, { recursive: true, force: true });
-      const { existsSync: existsSync5 } = await import("fs");
+      const { existsSync: existsSync9 } = await import("fs");
       const { cp } = await import("fs/promises");
-      if (existsSync5(outputDir)) {
+      if (existsSync9(outputDir)) {
         await cp(outputDir, stagingDir, { recursive: true });
       } else {
         await mkdir6(stagingDir, { recursive: true });
@@ -3243,7 +3326,7 @@ var ArtifactBundleWriter = class {
         manifestArtifacts.push({
           type: artifact.type,
           path: artifact.path,
-          checksum: "sha256:" + createHash("sha256").update(buffer).digest("hex"),
+          checksum: "sha256:" + createHash2("sha256").update(buffer).digest("hex"),
           sizeBytes: buffer.length
         });
       }
@@ -3255,7 +3338,7 @@ var ArtifactBundleWriter = class {
       };
       await writeFile7(join10(stagingDir, "artifact_manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
       let swapped = false;
-      if (existsSync5(outputDir)) {
+      if (existsSync9(outputDir)) {
         await rename(outputDir, oldDir);
         swapped = true;
       }
@@ -3293,7 +3376,7 @@ var JsonRenderer = class {
 // dist/export/renderers/HtmlRenderer.js
 import { join as join11, dirname as dirname3, relative as relative3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { existsSync as existsSync4, readFileSync, readdirSync, statSync } from "fs";
+import { existsSync as existsSync5, readFileSync, readdirSync, statSync } from "fs";
 var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
 function getAllFiles(dirPath, arrayOfFiles = []) {
   const files = readdirSync(dirPath);
@@ -3323,8 +3406,8 @@ var HtmlRenderer = class {
     ];
     let templateDir = "";
     for (const p of candidatePaths) {
-      if (existsSync4(p) && existsSync4(join11(p, "index.html"))) {
-        if (!existsSync4(join11(p, "vite.config.ts")) || p.endsWith("dist")) {
+      if (existsSync5(p) && existsSync5(join11(p, "index.html"))) {
+        if (!existsSync5(join11(p, "vite.config.ts")) || p.endsWith("dist")) {
           templateDir = p;
           break;
         }
@@ -3332,7 +3415,7 @@ var HtmlRenderer = class {
     }
     if (!templateDir) {
       for (const p of candidatePaths) {
-        if (existsSync4(join11(p, "index.html"))) {
+        if (existsSync5(join11(p, "index.html"))) {
           templateDir = p;
           break;
         }
@@ -3567,13 +3650,234 @@ var GraphRenderer = class {
   }
 };
 
+// dist/store/BlobStore.js
+import { createHash as createHash3 } from "crypto";
+import { mkdir as mkdir7, writeFile as writeFile8, open, rename as rename2, stat } from "fs/promises";
+import { existsSync as existsSync6 } from "fs";
+import { join as join12 } from "path";
+var BlobStore = class {
+  blobsDir;
+  tmpDir;
+  constructor(projectRoot) {
+    this.blobsDir = join12(projectRoot, ".vibe-splainer", "blobs");
+    this.tmpDir = join12(projectRoot, ".vibe-splainer", "tmp");
+  }
+  async ensureDirs() {
+    await mkdir7(this.blobsDir, { recursive: true });
+    await mkdir7(this.tmpDir, { recursive: true });
+  }
+  async writeAtomic(payload) {
+    await this.ensureDirs();
+    const buf = typeof payload === "string" ? Buffer.from(payload, "utf8") : payload;
+    const hex = createHash3("sha256").update(buf).digest("hex");
+    const contentHash = `sha256:${hex}`;
+    const blobPath = join12(this.blobsDir, `sha256_${hex}`);
+    if (existsSync6(blobPath)) {
+      return { contentHash, blobPath };
+    }
+    const tmpPath = join12(this.tmpDir, `tmp_${hex}_${Date.now()}`);
+    await writeFile8(tmpPath, buf);
+    const fh = await open(tmpPath, "r");
+    try {
+      await fh.datasync();
+    } finally {
+      await fh.close();
+    }
+    await rename2(tmpPath, blobPath);
+    return { contentHash, blobPath };
+  }
+  async readBlob(blobPath) {
+    const { readFile: readFile16 } = await import("fs/promises");
+    return readFile16(blobPath);
+  }
+  async blobExists(contentHash) {
+    const hex = contentHash.replace("sha256:", "");
+    const blobPath = join12(this.blobsDir, `sha256_${hex}`);
+    return existsSync6(blobPath);
+  }
+  blobPathForHash(contentHash) {
+    const hex = contentHash.replace("sha256:", "");
+    return join12(this.blobsDir, `sha256_${hex}`);
+  }
+  async verifyIntegrity(blobPath, expectedHash) {
+    try {
+      const { readFile: readFile16 } = await import("fs/promises");
+      const buf = await readFile16(blobPath);
+      const hex = createHash3("sha256").update(buf).digest("hex");
+      return `sha256:${hex}` === expectedHash;
+    } catch {
+      return false;
+    }
+  }
+  /** List all blob paths for GC reference counting */
+  async listBlobPaths() {
+    try {
+      const { readdir: readdir3 } = await import("fs/promises");
+      const files = await readdir3(this.blobsDir);
+      return files.filter((f) => f.startsWith("sha256_")).map((f) => join12(this.blobsDir, f));
+    } catch {
+      return [];
+    }
+  }
+  async getBlobSize(blobPath) {
+    try {
+      const info = await stat(blobPath);
+      return info.size;
+    } catch {
+      return 0;
+    }
+  }
+};
+async function hashFile(filePath) {
+  const { readFile: readFile16 } = await import("fs/promises");
+  const buf = await readFile16(filePath);
+  return `sha256:${createHash3("sha256").update(buf).digest("hex")}`;
+}
+
+// dist/store/PointerStore.js
+import Database from "better-sqlite3";
+import { join as join13 } from "path";
+import { mkdirSync } from "fs";
+import { Mutex } from "async-mutex";
+var instance = null;
+var PointerStore = class _PointerStore {
+  db;
+  writeMutex = new Mutex();
+  constructor(projectRoot) {
+    const dir = join13(projectRoot, ".vibe-splainer");
+    mkdirSync(dir, { recursive: true });
+    this.db = new Database(join13(dir, "pointer_store.db"));
+    this.db.pragma("busy_timeout = 5000");
+    this.db.pragma("journal_mode = WAL");
+    this.db.pragma("foreign_keys = ON");
+    this._migrate();
+  }
+  static open(projectRoot) {
+    if (!instance)
+      instance = new _PointerStore(projectRoot);
+    return instance;
+  }
+  static reset() {
+    instance = null;
+  }
+  _migrate() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS pointers (
+        pointerId     TEXT PRIMARY KEY,
+        scanId        TEXT NOT NULL,
+        artifactName  TEXT NOT NULL,
+        contentHash   TEXT NOT NULL,
+        blobPath      TEXT NOT NULL,
+        schemaVersion TEXT NOT NULL DEFAULT '1.0.0',
+        createdAt     INTEGER NOT NULL,
+        expiresAt     INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_pointers_scan ON pointers(scanId);
+      CREATE INDEX IF NOT EXISTS idx_pointers_hash ON pointers(contentHash);
+
+      CREATE TABLE IF NOT EXISTS work_orders (
+        workOrderId   TEXT PRIMARY KEY,
+        intent        TEXT NOT NULL,
+        allowedFiles  TEXT NOT NULL DEFAULT '[]',
+        allowedGlobs  TEXT NOT NULL DEFAULT '[]',
+        deniedGlobs   TEXT NOT NULL DEFAULT '[]',
+        requiredProof TEXT NOT NULL DEFAULT '[]',
+        status        TEXT NOT NULL DEFAULT 'pending',
+        createdAt     INTEGER NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS receipts (
+        receiptId     TEXT PRIMARY KEY,
+        workOrderId   TEXT NOT NULL REFERENCES work_orders(workOrderId),
+        status        TEXT NOT NULL,
+        proofPointers TEXT NOT NULL DEFAULT '[]',
+        changedFiles  TEXT NOT NULL DEFAULT '[]',
+        summary       TEXT NOT NULL DEFAULT '',
+        createdAt     INTEGER NOT NULL,
+        FOREIGN KEY (workOrderId) REFERENCES work_orders(workOrderId)
+      );
+    `);
+  }
+  async insertPointer(row) {
+    await this.writeMutex.runExclusive(() => {
+      this.db.prepare(`
+        INSERT OR REPLACE INTO pointers
+          (pointerId, scanId, artifactName, contentHash, blobPath, schemaVersion, createdAt, expiresAt)
+        VALUES
+          (@pointerId, @scanId, @artifactName, @contentHash, @blobPath, @schemaVersion, @createdAt, @expiresAt)
+      `).run(row);
+    });
+  }
+  getPointer(pointerId) {
+    return this.db.prepare("SELECT * FROM pointers WHERE pointerId = ?").get(pointerId) ?? null;
+  }
+  listPointersByScan(scanId) {
+    return this.db.prepare("SELECT * FROM pointers WHERE scanId = ?").all(scanId);
+  }
+  async insertWorkOrder(row) {
+    await this.writeMutex.runExclusive(() => {
+      this.db.prepare(`
+        INSERT OR REPLACE INTO work_orders
+          (workOrderId, intent, allowedFiles, allowedGlobs, deniedGlobs, requiredProof, status, createdAt)
+        VALUES
+          (@workOrderId, @intent, @allowedFiles, @allowedGlobs, @deniedGlobs, @requiredProof, @status, @createdAt)
+      `).run(row);
+    });
+  }
+  getWorkOrder(workOrderId) {
+    return this.db.prepare("SELECT * FROM work_orders WHERE workOrderId = ?").get(workOrderId) ?? null;
+  }
+  async updateWorkOrderStatus(workOrderId, status) {
+    await this.writeMutex.runExclusive(() => {
+      this.db.prepare("UPDATE work_orders SET status = ? WHERE workOrderId = ?").run(status, workOrderId);
+    });
+  }
+  async insertReceipt(receipt) {
+    await this.writeMutex.runExclusive(() => {
+      this.db.prepare(`
+        INSERT OR REPLACE INTO receipts
+          (receiptId, workOrderId, status, proofPointers, changedFiles, summary, createdAt)
+        VALUES
+          (@receiptId, @workOrderId, @status, @proofPointers, @changedFiles, @summary, @createdAt)
+      `).run({
+        ...receipt,
+        proofPointers: JSON.stringify(receipt.proofPointers),
+        changedFiles: JSON.stringify(receipt.changedFiles),
+        createdAt: Date.now()
+      });
+    });
+  }
+  /** GC: delete pointers older than cutoffMs and not pinned, return deleted count */
+  async gcScanPointers(keepScanIds) {
+    return await this.writeMutex.runExclusive(() => {
+      const placeholders = keepScanIds.map(() => "?").join(",");
+      const whereClause = keepScanIds.length > 0 ? `WHERE scanId NOT IN (${placeholders})` : "";
+      const result = this.db.prepare(`DELETE FROM pointers ${whereClause}`).run(...keepScanIds);
+      return result.changes;
+    });
+  }
+  listAllScanIds() {
+    const rows = this.db.prepare("SELECT DISTINCT scanId FROM pointers").all();
+    return rows.map((r) => r.scanId);
+  }
+  countPointers() {
+    const row = this.db.prepare("SELECT COUNT(*) as cnt FROM pointers").get();
+    return row.cnt;
+  }
+  close() {
+    this.db.close();
+    instance = null;
+  }
+};
+
 // dist/export/ExportOrchestrator.js
+import { v4 as uuidv4 } from "uuid";
 var ExportOrchestrator = class {
   projectRoot;
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
   }
-  async writeBundle(dossier, options = {}, store, graph) {
+  async writeBundle(dossier, options = {}, store, graph, scanId) {
     const finalStore = store || await readAnalysis(this.projectRoot);
     if (!finalStore) {
       throw new Error("Analysis store not found. Scan the project first.");
@@ -3605,6 +3909,83 @@ var ExportOrchestrator = class {
     }
     const writer = new ArtifactBundleWriter(this.projectRoot);
     await writer.writeBundle(artifacts);
+    const effectiveScanId = scanId ?? `scan_${Date.now()}`;
+    const blobStore = new BlobStore(this.projectRoot);
+    const pointerStore = PointerStore.open(this.projectRoot);
+    const now = Date.now();
+    const manifestEntries = [];
+    for (const artifact of artifacts) {
+      const content = typeof artifact.content === "string" ? Buffer.from(artifact.content, "utf8") : artifact.content;
+      const { contentHash, blobPath } = await blobStore.writeAtomic(content);
+      const pointerId = `ptr_${uuidv4().replace(/-/g, "").slice(0, 16)}`;
+      await pointerStore.insertPointer({
+        pointerId,
+        scanId: effectiveScanId,
+        artifactName: artifact.type,
+        contentHash,
+        blobPath,
+        schemaVersion: "1.0.0",
+        createdAt: now,
+        expiresAt: null
+      });
+      const entry = {
+        name: artifact.type,
+        pointer: pointerId,
+        contentHash,
+        sizeBytes: content.length
+      };
+      if (artifact.type === "analysis") {
+        entry.hydrators = ["get_project_summary", "get_start_here"];
+        const analysisIndex = {
+          schemaVersion: "1.0.0",
+          scanId: effectiveScanId,
+          startHere: dossier.map.topGravity.slice(0, 12),
+          topHeat: dossier.map.topHeat.slice(0, 12),
+          pillarSummary: dossier.map.pillars.map((p) => ({
+            name: p.name,
+            fileCount: p.memberFiles?.length ?? 0
+          })),
+          totalFiles: Object.keys(finalStore.files).length,
+          realSourceFiles: Object.values(finalStore.files).filter((f) => f.isRealSource).length
+        };
+        const indexContent = Buffer.from(JSON.stringify(analysisIndex, null, 2), "utf8");
+        const indexWrite = await blobStore.writeAtomic(indexContent);
+        const indexPointerId = `ptr_${uuidv4().replace(/-/g, "").slice(0, 16)}`;
+        await pointerStore.insertPointer({
+          pointerId: indexPointerId,
+          scanId: effectiveScanId,
+          artifactName: "analysis.index",
+          contentHash: indexWrite.contentHash,
+          blobPath: indexWrite.blobPath,
+          schemaVersion: "1.0.0",
+          createdAt: now,
+          expiresAt: null
+        });
+        entry.indexes = { startHere: indexPointerId };
+      }
+      manifestEntries.push(entry);
+    }
+    const manifest = {
+      schemaVersion: "2.0.0",
+      scanId: effectiveScanId,
+      generatedAt: new Date(now).toISOString(),
+      projectRoot: this.projectRoot,
+      artifacts: manifestEntries
+    };
+    const manifestContent = Buffer.from(JSON.stringify(manifest, null, 2), "utf8");
+    const manifestWrite = await blobStore.writeAtomic(manifestContent);
+    const manifestPointerId = `ptr_manifest_${effectiveScanId}`;
+    await pointerStore.insertPointer({
+      pointerId: manifestPointerId,
+      scanId: effectiveScanId,
+      artifactName: "artifact_manifest",
+      contentHash: manifestWrite.contentHash,
+      blobPath: manifestWrite.blobPath,
+      schemaVersion: "2.0.0",
+      createdAt: now,
+      expiresAt: null
+    });
+    return { scanId: effectiveScanId, manifestPointer: manifestPointerId };
   }
   buildViewModel(dossier, store) {
     const recommendations = {};
@@ -3631,9 +4012,9 @@ var ExportOrchestrator = class {
 
 // dist/export/Watcher.js
 import chokidar from "chokidar";
-import { createHash as createHash2 } from "crypto";
-import { readFile as readFile9 } from "fs/promises";
-import { join as join12 } from "path";
+import { createHash as createHash4 } from "crypto";
+import { readFile as readFile10 } from "fs/promises";
+import { join as join14 } from "path";
 var activeWatchers = /* @__PURE__ */ new Map();
 async function startWatcher(projectRoot, watchedPaths) {
   const existing = activeWatchers.get(projectRoot);
@@ -3651,14 +4032,14 @@ async function startWatcher(projectRoot, watchedPaths) {
       const dossier = await readDossier(projectRoot);
       if (!dossier)
         return;
-      const content = await readFile9(filepath, "utf8");
-      const newHash = createHash2("sha256").update(content).digest("hex");
+      const content = await readFile10(filepath, "utf8");
+      const newHash = createHash4("sha256").update(content).digest("hex");
       let mutated = false;
       for (const pillar of dossier.pillars) {
         for (const card of pillar.decisions) {
           if (!card.primaryFile)
             continue;
-          const absMatch = filepath === join12(projectRoot, card.primaryFile) || filepath.endsWith("/" + card.primaryFile);
+          const absMatch = filepath === join14(projectRoot, card.primaryFile) || filepath.endsWith("/" + card.primaryFile);
           if (absMatch && card.lastScannedHash !== newHash) {
             card.status = "stale";
             const rel = card.primaryFile;
@@ -3726,12 +4107,13 @@ async function handleScanProject(args, options = {}) {
       dossier.pillars.push({ name: def.name, cardCount: 0, decisions: [] });
     }
   }
+  const scanId = `scan_${Date.now()}`;
   const orchestrator = new ExportOrchestrator(projectRoot);
-  await orchestrator.writeBundle(dossier, {
+  const { manifestPointer } = await orchestrator.writeBundle(dossier, {
     format: options.format,
     budget: options.budget ? parseInt(options.budget, 10) : void 0,
     scope: options.scope
-  }, result.store, result.graph);
+  }, result.store, result.graph, scanId);
   await startWatcher(projectRoot, result.files.map((f) => f.path));
   console.error(`[vibe-splain] Scan complete. ${result.totalFilesScanned} files, ${result.realSourceCount} real-source, ${result.wildCandidates.length} wild candidates.`);
   const validation = result.validation ?? { passed: true, errors: 0, warnings: 0, reportPath: ".vibe-splainer/validation_report.json" };
@@ -3742,6 +4124,8 @@ async function handleScanProject(args, options = {}) {
   return {
     ok: true,
     message: statusMsg,
+    scanId,
+    manifestPointer,
     validation: {
       passed: validation.passed,
       errors: validation.errors,
@@ -3855,8 +4239,8 @@ async function handleSetProjectBrief(args, options = {}) {
 }
 
 // dist/mcp/tools/get_file_context.js
-import { readFile as readFile10 } from "fs/promises";
-import { join as join13, relative as relative4, isAbsolute } from "path";
+import { readFile as readFile11 } from "fs/promises";
+import { join as join15, relative as relative4, isAbsolute } from "path";
 var getFileContextTool = {
   name: "get_file_context",
   description: "Returns PRE-EXTRACTED evidence for a file so you do not have to read the whole thing and paraphrase its header comment. Returns: gravity/heat scores + signals, importedBy (named fan-in \u2014 use this for blastRadius), hotSpans (the gnarliest function bodies, comment-stripped, each with a reason), smellSpans (located tech debt with \xB13 lines of context), and signature (the exported API surface). Base your evidence on hotSpans/smellSpans \u2014 NEVER on header comments. Pass { full: true } only if you truly need the raw source.",
@@ -3876,7 +4260,7 @@ async function handleGetFileContext(args) {
   const full = args.full === true;
   if (!projectRoot || !filePath)
     throw new Error("projectRoot and filePath are required");
-  const fullPath = isAbsolute(filePath) ? filePath : join13(projectRoot, filePath);
+  const fullPath = isAbsolute(filePath) ? filePath : join15(projectRoot, filePath);
   const relPath = relative4(projectRoot, fullPath);
   const evidence = await getFileAnalysis(fullPath);
   if (!evidence) {
@@ -3901,16 +4285,16 @@ async function handleGetFileContext(args) {
     smellSpans: evidence.smellSpans
   };
   if (full) {
-    result.source = await readFile10(fullPath, "utf8");
+    result.source = await readFile11(fullPath, "utf8");
   }
   return result;
 }
 
 // dist/mcp/tools/write_decision_card.js
-import { v4 as uuidv4 } from "uuid";
-import { createHash as createHash3 } from "crypto";
-import { readFile as readFile11 } from "fs/promises";
-import { join as join14 } from "path";
+import { v4 as uuidv42 } from "uuid";
+import { createHash as createHash5 } from "crypto";
+import { readFile as readFile12 } from "fs/promises";
+import { join as join16 } from "path";
 var CATEGORIES = ["Bottleneck", "Hack", "Smart-Move", "Risk", "Convention", "Dead-Weight"];
 function normalizeSnippet(s) {
   let out = (s ?? "").replace(/\r\n/g, "\n");
@@ -4007,12 +4391,12 @@ async function handleWriteDecisionCard(args, options = {}) {
   const heat = persisted ? Math.round(persisted.heat) : void 0;
   let primaryContent = "";
   try {
-    primaryContent = await readFile11(join14(projectRoot, primaryFile), "utf8");
+    primaryContent = await readFile12(join16(projectRoot, primaryFile), "utf8");
   } catch {
   }
-  const hash = createHash3("sha256").update(primaryContent).digest("hex");
+  const hash = createHash5("sha256").update(primaryContent).digest("hex");
   const card = {
-    id: uuidv4(),
+    id: uuidv42(),
     pillar,
     title,
     thesis,
@@ -4286,6 +4670,856 @@ async function handleGetCallChain(args) {
   }
 }
 
+// dist/mcp/tools/get_file_skeleton.js
+import { readFile as readFile13 } from "fs/promises";
+import { join as join17 } from "path";
+
+// dist/mcp/SessionScope.js
+import { minimatch } from "minimatch";
+var ScopeViolation = class extends Error {
+  path;
+  workOrderId;
+  constructor(path, workOrderId, reason) {
+    super(`ScopeViolation [${workOrderId}]: ${reason} \u2014 path: ${path}`);
+    this.path = path;
+    this.workOrderId = workOrderId;
+    this.name = "ScopeViolation";
+  }
+};
+var activeScope = null;
+var SessionScope = {
+  set(policy) {
+    activeScope = policy;
+  },
+  clear() {
+    activeScope = null;
+  },
+  get() {
+    return activeScope;
+  },
+  /**
+   * Enforce scope for a file path.
+   * Throws ScopeViolation if:
+   *  - a scope is active AND the path is not allowed
+   * If no scope is active, all paths are permitted.
+   */
+  enforce(filePath) {
+    if (!activeScope)
+      return;
+    const { workOrderId, allowedFiles, allowedGlobs, deniedGlobs } = activeScope;
+    const inAllowedFiles = allowedFiles.some((f) => filePath === f || filePath.endsWith("/" + f) || filePath.endsWith(f));
+    const inAllowedGlobs = allowedGlobs.some((g) => minimatch(filePath, g, { matchBase: true }));
+    if (!inAllowedFiles && !inAllowedGlobs) {
+      throw new ScopeViolation(filePath, workOrderId, "path not in allowedFiles or allowedGlobs");
+    }
+    const isDenied = deniedGlobs.some((g) => minimatch(filePath, g, { matchBase: true }));
+    if (isDenied) {
+      throw new ScopeViolation(filePath, workOrderId, "path matches deniedGlobs");
+    }
+  },
+  fromWorkOrderRow(row) {
+    return {
+      workOrderId: row.workOrderId,
+      allowedFiles: JSON.parse(row.allowedFiles),
+      allowedGlobs: JSON.parse(row.allowedGlobs),
+      deniedGlobs: JSON.parse(row.deniedGlobs),
+      requiredProof: JSON.parse(row.requiredProof)
+    };
+  }
+};
+
+// dist/mcp/BudgetGuard.js
+import { v4 as uuidv43 } from "uuid";
+var BUDGET_CHARS = 8e3;
+async function applyBudgetGuard(projectRoot, scanId, artifactName, output) {
+  const serialized = JSON.stringify(output, null, 2);
+  if (serialized.length <= BUDGET_CHARS)
+    return output;
+  const blobStore = new BlobStore(projectRoot);
+  const pointerStore = PointerStore.open(projectRoot);
+  const { contentHash, blobPath } = await blobStore.writeAtomic(serialized);
+  const pointerId = `ptr_${uuidv43().replace(/-/g, "").slice(0, 16)}`;
+  await pointerStore.insertPointer({
+    pointerId,
+    scanId,
+    artifactName,
+    contentHash,
+    blobPath,
+    schemaVersion: "1.0.0",
+    createdAt: Date.now(),
+    expiresAt: null
+  });
+  const result = {
+    pointerId,
+    contentHash,
+    sizeBytes: serialized.length,
+    summary: `Output exceeded context budget (${serialized.length} chars). Written to artifact blob.`,
+    hydrators: ["get_evidence_slice", "get_start_here", "get_project_summary"]
+  };
+  return result;
+}
+async function hydratePointer(projectRoot, pointerId) {
+  const pointerStore = PointerStore.open(projectRoot);
+  const row = pointerStore.getPointer(pointerId);
+  if (!row) {
+    throw new Error(`ArtifactNotFound: pointer ${pointerId} does not exist`);
+  }
+  if (row.expiresAt !== null && row.expiresAt < Date.now()) {
+    throw new Error(`ArtifactCollectedError: pointer ${pointerId} has expired`);
+  }
+  const SUPPORTED_VERSIONS = ["1.0.0", "2.0.0"];
+  if (!SUPPORTED_VERSIONS.includes(row.schemaVersion)) {
+    throw new Error(`UnsupportedSchema: pointer ${pointerId} has schema version ${row.schemaVersion}`);
+  }
+  const blobStore = new BlobStore(projectRoot);
+  const content = await blobStore.readBlob(row.blobPath);
+  const valid = await blobStore.verifyIntegrity(row.blobPath, row.contentHash);
+  if (!valid) {
+    throw new Error(`IntegrityError: blob for pointer ${pointerId} failed hash verification`);
+  }
+  return { content, row };
+}
+
+// dist/mcp/tools/get_file_skeleton.js
+import { v4 as uuidv44 } from "uuid";
+var getFileSkeletonTool = {
+  name: "get_file_skeleton",
+  description: "Returns a content-addressed skeleton view of a source file (function signatures, class names, exported symbols). Enforces active workOrder scope. Results are content-addressed \u2014 repeated calls on unchanged files return cached pointers.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectRoot: { type: "string", description: "Absolute project root" },
+      filePath: { type: "string", description: "Path relative to projectRoot" },
+      scanId: { type: "string", description: "Current scan ID for pointer registration" }
+    },
+    required: ["projectRoot", "filePath", "scanId"]
+  }
+};
+async function handleGetFileSkeleton(args) {
+  const projectRoot = args.projectRoot;
+  const filePath = args.filePath;
+  const scanId = args.scanId;
+  if (!projectRoot || !filePath || !scanId) {
+    throw new Error("projectRoot, filePath, and scanId are required");
+  }
+  try {
+    SessionScope.enforce(filePath);
+  } catch (e) {
+    if (e instanceof ScopeViolation)
+      throw e;
+    throw e;
+  }
+  const absolutePath = filePath.startsWith("/") ? filePath : join17(projectRoot, filePath);
+  let currentHash;
+  try {
+    currentHash = await hashFile(absolutePath);
+  } catch {
+    throw new Error(`FileNotFound: cannot read ${filePath}`);
+  }
+  const parserVersion = "1.0.0";
+  const cacheKey = `skeleton:${currentHash}:${parserVersion}`;
+  const pointerStore = PointerStore.open(projectRoot);
+  const existingPointers = pointerStore.listPointersByScan(scanId);
+  const cached = existingPointers.find((p) => p.artifactName === "file_skeleton" && p.contentHash === cacheKey);
+  if (cached) {
+    return {
+      pointerId: cached.pointerId,
+      contentHash: currentHash,
+      cached: true,
+      filePath
+    };
+  }
+  const source = await readFile13(absolutePath, "utf8");
+  const skeleton = extractSkeleton(source, filePath);
+  const skeletonPayload = {
+    filePath,
+    sourceHash: currentHash,
+    parserVersion,
+    skeleton
+  };
+  const blobStore = new BlobStore(projectRoot);
+  const serialized = JSON.stringify(skeletonPayload, null, 2);
+  const { contentHash: skeletonHash, blobPath } = await blobStore.writeAtomic(serialized);
+  const pointerId = `ptr_skel_${uuidv44().replace(/-/g, "").slice(0, 12)}`;
+  await pointerStore.insertPointer({
+    pointerId,
+    scanId,
+    artifactName: "file_skeleton",
+    contentHash: cacheKey,
+    // cache key encodes source hash + parser version
+    blobPath,
+    schemaVersion: "1.0.0",
+    createdAt: Date.now(),
+    expiresAt: null
+  });
+  const result = {
+    filePath,
+    sourceHash: currentHash,
+    pointerId,
+    skeleton
+  };
+  return await applyBudgetGuard(projectRoot, scanId, "file_skeleton", result);
+}
+function extractSkeleton(source, filePath) {
+  const lines = source.split("\n");
+  const skeleton = [];
+  const ext = filePath.split(".").pop() ?? "";
+  const isTS = ["ts", "tsx"].includes(ext);
+  const isJS = ["js", "jsx", "mjs", "cjs"].includes(ext);
+  if (isTS || isJS) {
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (/^(export\s+)?(async\s+)?function\b/.test(line) || /^(export\s+)?(abstract\s+)?class\b/.test(line) || /^(export\s+)?interface\b/.test(line) || /^(export\s+)?type\s+\w+/.test(line) || /^(export\s+)?enum\b/.test(line) || /^(export\s+)?const\s+\w+\s*[:=(]/.test(line) || /^(export\s+)?let\s+\w+\s*[:=(]/.test(line) || /^(export\s+)?(default\s+)/.test(line) || /^\s*(public|private|protected|static|readonly|abstract)\s+/.test(line) || /^import\b/.test(line)) {
+        skeleton.push(`L${i + 1}: ${lines[i]}`);
+      }
+    }
+  } else {
+    return lines.slice(0, 80).map((l, i) => `L${i + 1}: ${l}`);
+  }
+  return skeleton;
+}
+
+// dist/mcp/tools/read_file.js
+import { readFile as readFile14 } from "fs/promises";
+import { join as join18 } from "path";
+import { v4 as uuidv45 } from "uuid";
+var readFileTool = {
+  name: "read_file",
+  description: "Reads a file within the active workOrder scope. Enforces allowedFiles/allowedGlobs/deniedGlobs. Records content hash. Output is budgeted.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectRoot: { type: "string", description: "Absolute project root" },
+      filePath: { type: "string", description: "Path relative to projectRoot" },
+      scanId: { type: "string", description: "Current scan ID for pointer registration" },
+      startLine: { type: "number", description: "Optional: 1-based start line to return a slice" },
+      endLine: { type: "number", description: "Optional: 1-based end line (inclusive). Capped at startLine+500." }
+    },
+    required: ["projectRoot", "filePath", "scanId"]
+  }
+};
+async function handleReadFile(args) {
+  const projectRoot = args.projectRoot;
+  const filePath = args.filePath;
+  const scanId = args.scanId;
+  const startLine = args.startLine !== void 0 ? Number(args.startLine) : void 0;
+  const endLine = args.endLine !== void 0 ? Math.min(Number(args.endLine), (startLine ?? 1) + 500) : void 0;
+  if (!projectRoot || !filePath || !scanId) {
+    throw new Error("projectRoot, filePath, and scanId are required");
+  }
+  try {
+    SessionScope.enforce(filePath);
+  } catch (e) {
+    if (e instanceof ScopeViolation)
+      throw e;
+    throw e;
+  }
+  const absolutePath = filePath.startsWith("/") ? filePath : join18(projectRoot, filePath);
+  let content;
+  try {
+    content = await readFile14(absolutePath, "utf8");
+  } catch {
+    throw new Error(`FileNotFound: cannot read ${filePath}`);
+  }
+  const contentHash = await hashFile(absolutePath);
+  let output = content;
+  let sliceInfo;
+  if (startLine !== void 0) {
+    const lines = content.split("\n");
+    const end = endLine ?? lines.length;
+    output = lines.slice(startLine - 1, end).join("\n");
+    sliceInfo = { startLine, endLine: end, totalLines: lines.length };
+  }
+  const blobStore = new BlobStore(projectRoot);
+  const pointerStore = PointerStore.open(projectRoot);
+  const { blobPath } = await blobStore.writeAtomic(content);
+  const pointerId = `ptr_file_${uuidv45().replace(/-/g, "").slice(0, 12)}`;
+  await pointerStore.insertPointer({
+    pointerId,
+    scanId,
+    artifactName: "file_read",
+    contentHash,
+    blobPath,
+    schemaVersion: "1.0.0",
+    createdAt: Date.now(),
+    expiresAt: null
+  });
+  const result = {
+    filePath,
+    contentHash,
+    pointerId,
+    content: output
+  };
+  if (sliceInfo)
+    result.slice = sliceInfo;
+  return await applyBudgetGuard(projectRoot, scanId, "file_read", result);
+}
+
+// dist/mcp/tools/apply_patch.js
+import { writeFile as writeFile9, rename as rename3, mkdir as mkdir8 } from "fs/promises";
+import { join as join19, dirname as dirname4 } from "path";
+import { v4 as uuidv46 } from "uuid";
+var StalePatchError = class extends Error {
+  filePath;
+  expectedHash;
+  actualHash;
+  constructor(filePath, expectedHash, actualHash) {
+    super(`StalePatchError: ${filePath} hash mismatch \u2014 expected ${expectedHash}, got ${actualHash}. File was modified since the expectedPrePatchHash was computed. Re-read the file and regenerate the patch.`);
+    this.filePath = filePath;
+    this.expectedHash = expectedHash;
+    this.actualHash = actualHash;
+    this.name = "StalePatchError";
+  }
+};
+var applyPatchTool = {
+  name: "apply_patch",
+  description: "Applies a text patch to a file within the active workOrder scope. Requires expectedPrePatchHash to prevent stale-patch corruption. Records pre- and post-patch hashes.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectRoot: { type: "string", description: "Absolute project root" },
+      filePath: { type: "string", description: "Path relative to projectRoot" },
+      newContent: { type: "string", description: "Full new content of the file after the patch" },
+      expectedPrePatchHash: {
+        type: "string",
+        description: "sha256:<hex> hash of the file BEFORE patching. Obtain via hashFile or the sourceHash from get_file_skeleton."
+      },
+      scanId: { type: "string", description: "Current scan ID for pointer registration" }
+    },
+    required: ["projectRoot", "filePath", "newContent", "expectedPrePatchHash", "scanId"]
+  }
+};
+async function handleApplyPatch(args) {
+  const projectRoot = args.projectRoot;
+  const filePath = args.filePath;
+  const newContent = args.newContent;
+  const expectedPrePatchHash = args.expectedPrePatchHash;
+  const scanId = args.scanId;
+  if (!projectRoot || !filePath || !newContent || !expectedPrePatchHash || !scanId) {
+    throw new Error("projectRoot, filePath, newContent, expectedPrePatchHash, and scanId are all required");
+  }
+  try {
+    SessionScope.enforce(filePath);
+  } catch (e) {
+    if (e instanceof ScopeViolation)
+      throw e;
+    throw e;
+  }
+  const absolutePath = filePath.startsWith("/") ? filePath : join19(projectRoot, filePath);
+  let actualPreHash;
+  try {
+    actualPreHash = await hashFile(absolutePath);
+  } catch {
+    actualPreHash = "sha256:new";
+  }
+  if (actualPreHash !== expectedPrePatchHash) {
+    throw new StalePatchError(filePath, expectedPrePatchHash, actualPreHash);
+  }
+  const dir = dirname4(absolutePath);
+  await mkdir8(dir, { recursive: true });
+  const tmpPath = absolutePath + `.tmp_${Date.now()}`;
+  await writeFile9(tmpPath, newContent, "utf8");
+  await rename3(tmpPath, absolutePath);
+  const postPatchHash = await hashFile(absolutePath);
+  const blobStore = new BlobStore(projectRoot);
+  const pointerStore = PointerStore.open(projectRoot);
+  const { blobPath } = await blobStore.writeAtomic(newContent);
+  const pointerId = `ptr_patch_${uuidv46().replace(/-/g, "").slice(0, 12)}`;
+  await pointerStore.insertPointer({
+    pointerId,
+    scanId,
+    artifactName: "patch_record",
+    contentHash: postPatchHash,
+    blobPath,
+    schemaVersion: "1.0.0",
+    createdAt: Date.now(),
+    expiresAt: null
+  });
+  const result = {
+    ok: true,
+    filePath,
+    prePatchHash: actualPreHash,
+    postPatchHash,
+    pointerId,
+    message: `Patch applied to ${filePath}`
+  };
+  return await applyBudgetGuard(projectRoot, scanId, "patch_record", result);
+}
+
+// dist/mcp/tools/work_orders.js
+import { v4 as uuidv47 } from "uuid";
+var createWorkOrderTool = {
+  name: "create_work_order",
+  description: "Creates a new Work Order defining intent, allowed file scope, and required verifiable proof. Returns the workOrderId and a manifestPointer for use with spawn_worker.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectRoot: { type: "string", description: "Absolute project root" },
+      intent: { type: "string", description: "Plain-language description of what the worker should do" },
+      allowedFiles: {
+        type: "array",
+        items: { type: "string" },
+        description: "Explicit file paths (relative to projectRoot) the worker may read/write"
+      },
+      allowedGlobs: {
+        type: "array",
+        items: { type: "string" },
+        description: "Glob patterns for allowed files"
+      },
+      deniedGlobs: {
+        type: "array",
+        items: { type: "string" },
+        description: "Glob patterns that override allowedFiles/allowedGlobs"
+      },
+      requiredProof: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            proofId: { type: "string" },
+            schemaName: { type: "string", description: "e.g. test_report.v1, patch_hash" },
+            description: { type: "string" }
+          },
+          required: ["proofId", "schemaName", "description"]
+        },
+        description: "Machine-verifiable evidence the worker must provide"
+      }
+    },
+    required: ["projectRoot", "intent", "allowedFiles"]
+  }
+};
+async function handleCreateWorkOrder(args) {
+  const projectRoot = args.projectRoot;
+  const intent = args.intent;
+  const allowedFiles = args.allowedFiles ?? [];
+  const allowedGlobs = args.allowedGlobs ?? [];
+  const deniedGlobs = args.deniedGlobs ?? [];
+  const requiredProof = args.requiredProof ?? [];
+  if (!projectRoot || !intent) {
+    throw new Error("projectRoot and intent are required");
+  }
+  const workOrderId = `wo_${uuidv47().replace(/-/g, "").slice(0, 16)}`;
+  const pointerStore = PointerStore.open(projectRoot);
+  await pointerStore.insertWorkOrder({
+    workOrderId,
+    intent,
+    allowedFiles: JSON.stringify(allowedFiles),
+    allowedGlobs: JSON.stringify(allowedGlobs),
+    deniedGlobs: JSON.stringify(deniedGlobs),
+    requiredProof: JSON.stringify(requiredProof),
+    status: "pending",
+    createdAt: Date.now()
+  });
+  return {
+    ok: true,
+    workOrderId,
+    intent,
+    allowedFiles,
+    allowedGlobs,
+    deniedGlobs,
+    requiredProof,
+    nextStep: `Call spawn_worker with workOrderId "${workOrderId}" to generate a DelegationRequest`
+  };
+}
+var spawnWorkerTool = {
+  name: "spawn_worker",
+  description: "Generates a DelegationRequest from a Work Order. The Client Orchestrator uses this object to spawn an isolated Worker session. The MCP server does NOT spawn any subprocess.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectRoot: { type: "string", description: "Absolute project root" },
+      workOrderId: { type: "string", description: "ID returned by create_work_order" }
+    },
+    required: ["projectRoot", "workOrderId"]
+  }
+};
+async function handleSpawnWorker(args) {
+  const projectRoot = args.projectRoot;
+  const workOrderId = args.workOrderId;
+  if (!projectRoot || !workOrderId) {
+    throw new Error("projectRoot and workOrderId are required");
+  }
+  const pointerStore = PointerStore.open(projectRoot);
+  const row = pointerStore.getWorkOrder(workOrderId);
+  if (!row) {
+    throw new Error(`WorkOrderNotFound: ${workOrderId}`);
+  }
+  if (row.status === "completed" || row.status === "failed" || row.status === "active") {
+    throw new Error(`WorkOrderClosed: ${workOrderId} is already ${row.status}`);
+  }
+  await pointerStore.updateWorkOrderStatus(workOrderId, "active");
+  const delegationRequest = {
+    schemaVersion: "1.0.0",
+    workOrderId: row.workOrderId,
+    intent: row.intent,
+    sessionScope: {
+      allowedFiles: JSON.parse(row.allowedFiles),
+      allowedGlobs: JSON.parse(row.allowedGlobs),
+      deniedGlobs: JSON.parse(row.deniedGlobs)
+    },
+    requiredProof: JSON.parse(row.requiredProof),
+    instructions: [
+      `1. Call set_session_scope with workOrderId "${workOrderId}" before any file operations.`,
+      "2. Only read/write files within the sessionScope.",
+      "3. If you need a file outside scope, call yield_for_scope_expansion \u2014 do NOT proceed.",
+      "4. On completion, call submit_receipt with proof for every requiredProof entry."
+    ]
+  };
+  return {
+    ok: true,
+    delegationRequest,
+    note: "The Client Orchestrator must spawn the Worker session using this DelegationRequest. The MCP server does not spawn subprocesses."
+  };
+}
+
+// dist/mcp/tools/submit_receipt.js
+import { join as join20 } from "path";
+import { minimatch as minimatch2 } from "minimatch";
+import { v4 as uuidv48 } from "uuid";
+var submitReceiptTool = {
+  name: "submit_receipt",
+  description: "Worker submits a WorkerReceipt for a completed Work Order. The ProofValidator checks all 8 proof conditions. Returns accept/reject with detailed errors.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectRoot: { type: "string", description: "Absolute project root" },
+      receipt: {
+        type: "object",
+        description: "WorkerReceipt object",
+        properties: {
+          workOrderId: { type: "string" },
+          status: { type: "string", enum: ["completed", "failed", "blocked"] },
+          proofPointers: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                pointer: { type: "string" },
+                schemaName: { type: "string" },
+                contentHash: { type: "string" }
+              },
+              required: ["pointer", "schemaName", "contentHash"]
+            }
+          },
+          changedFiles: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                path: { type: "string" },
+                prePatchHash: { type: "string" },
+                postPatchHash: { type: "string" }
+              },
+              required: ["path", "prePatchHash", "postPatchHash"]
+            }
+          },
+          summary: { type: "string" }
+        },
+        required: ["workOrderId", "status", "proofPointers", "changedFiles", "summary"]
+      }
+    },
+    required: ["projectRoot", "receipt"]
+  }
+};
+async function handleSubmitReceipt(args) {
+  const projectRoot = args.projectRoot;
+  const receipt = args.receipt;
+  if (!projectRoot || !receipt) {
+    throw new Error("projectRoot and receipt are required");
+  }
+  const pointerStore = PointerStore.open(projectRoot);
+  const workOrder = pointerStore.getWorkOrder(receipt.workOrderId);
+  if (!workOrder) {
+    throw new Error(`WorkOrderNotFound: ${receipt.workOrderId}`);
+  }
+  if (workOrder.status !== "active") {
+    throw new Error(`WorkOrderNotActive: ${receipt.workOrderId} is "${workOrder.status}", expected "active"`);
+  }
+  const allowedFiles = JSON.parse(workOrder.allowedFiles);
+  const allowedGlobs = JSON.parse(workOrder.allowedGlobs);
+  const requiredProof = JSON.parse(workOrder.requiredProof);
+  const blobDir = join20(projectRoot, ".vibe-splainer", "blobs");
+  const isAllowedFile = (filePath) => {
+    const inExplicit = allowedFiles.some((f) => filePath === f || filePath.endsWith("/" + f) || filePath.endsWith(f));
+    const inGlobs = allowedGlobs.some((g) => minimatch2(filePath, g, { matchBase: true }));
+    return inExplicit || inGlobs;
+  };
+  const validation = await ProofValidator.validate(receipt, requiredProof, isAllowedFile, blobDir);
+  const receiptId = `rcpt_${uuidv48().replace(/-/g, "").slice(0, 16)}`;
+  const finalStatus = validation.valid ? receipt.status : "failed";
+  await pointerStore.insertReceipt({
+    receiptId,
+    workOrderId: receipt.workOrderId,
+    status: finalStatus,
+    proofPointers: receipt.proofPointers,
+    changedFiles: receipt.changedFiles,
+    summary: receipt.summary
+  });
+  await pointerStore.updateWorkOrderStatus(receipt.workOrderId, validation.valid ? receipt.status === "completed" ? "completed" : "failed" : "failed");
+  return {
+    receiptId,
+    accepted: validation.valid,
+    workOrderId: receipt.workOrderId,
+    validation,
+    finalStatus
+  };
+}
+
+// dist/mcp/tools/set_session_scope.js
+var setSessionScopeTool = {
+  name: "set_session_scope",
+  description: "Sets the active session scope from a Work Order. All subsequent file tools (read_file, get_file_skeleton, apply_patch) will enforce this scope until overwritten or the server restarts.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectRoot: { type: "string", description: "Absolute project root" },
+      workOrderId: { type: "string", description: "Work Order ID to load scope from" }
+    },
+    required: ["projectRoot", "workOrderId"]
+  }
+};
+async function handleSetSessionScope(args) {
+  const projectRoot = args.projectRoot;
+  const workOrderId = args.workOrderId;
+  if (!projectRoot || !workOrderId) {
+    throw new Error("projectRoot and workOrderId are required");
+  }
+  const pointerStore = PointerStore.open(projectRoot);
+  const row = pointerStore.getWorkOrder(workOrderId);
+  if (!row) {
+    throw new Error(`WorkOrderNotFound: ${workOrderId}`);
+  }
+  const policy = SessionScope.fromWorkOrderRow(row);
+  SessionScope.set(policy);
+  return {
+    ok: true,
+    workOrderId,
+    scope: {
+      allowedFiles: policy.allowedFiles,
+      allowedGlobs: policy.allowedGlobs,
+      deniedGlobs: policy.deniedGlobs,
+      requiredProofCount: policy.requiredProof.length
+    },
+    message: `Session scope set from work order ${workOrderId}. All file tools will enforce this scope.`
+  };
+}
+
+// dist/mcp/tools/yield_for_scope_expansion.js
+var yieldForScopeExpansionTool = {
+  name: "yield_for_scope_expansion",
+  description: "Worker signals that it needs to access files outside its current scope. Immediately terminates the active scope and returns a Blocked receipt. The Manager must evaluate the evidence and decide whether to spawn a new Worker with expanded scope.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      requestedPaths: {
+        type: "array",
+        items: { type: "string" },
+        description: "Paths the worker needs but cannot access under current scope"
+      },
+      reason: {
+        type: "string",
+        description: "Why these paths are needed \u2014 root cause found in out-of-scope file"
+      },
+      evidencePointers: {
+        type: "array",
+        items: { type: "string" },
+        description: "Pointer IDs for artifacts that justify the expansion request"
+      }
+    },
+    required: ["requestedPaths", "reason"]
+  }
+};
+async function handleYieldForScopeExpansion(args) {
+  const requestedPaths = args.requestedPaths ?? [];
+  const reason = args.reason;
+  const evidencePointers = args.evidencePointers ?? [];
+  if (!requestedPaths.length || !reason) {
+    throw new Error("requestedPaths and reason are required");
+  }
+  const currentScope = SessionScope.get();
+  const workOrderId = currentScope?.workOrderId ?? "unknown";
+  SessionScope.clear();
+  return {
+    status: "blocked",
+    workOrderId,
+    requestedPaths,
+    reason,
+    evidencePointers,
+    receipt: {
+      workOrderId,
+      status: "blocked",
+      proofPointers: [],
+      changedFiles: [],
+      summary: `Worker blocked: scope expansion required. Reason: ${reason}`
+    },
+    managerInstructions: [
+      "Worker has been terminated. Active session scope has been cleared.",
+      "Evaluate the evidence pointers and reason.",
+      "If expansion is warranted, create a new Work Order with the expanded allowedFiles and spawn a new Worker.",
+      "If expansion is NOT warranted, the task is failed \u2014 do not retry with same scope."
+    ]
+  };
+}
+
+// dist/mcp/tools/hydration/get_start_here.js
+var getStartHereTool = {
+  name: "get_start_here",
+  description: "Hydrates the start-here index for a scan manifest pointer. Returns the top 5 highest-gravity files. Pointer must be valid and unexpired.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectRoot: { type: "string", description: "Absolute project root" },
+      manifestPointer: { type: "string", description: "Pointer ID for the scan manifest or analysis.index artifact" },
+      scanId: { type: "string", description: "Current scan ID for budget pointer registration" }
+    },
+    required: ["projectRoot", "manifestPointer", "scanId"]
+  }
+};
+async function handleGetStartHere(args) {
+  const projectRoot = args.projectRoot;
+  const manifestPointer = args.manifestPointer;
+  const scanId = args.scanId;
+  if (!projectRoot || !manifestPointer || !scanId) {
+    throw new Error("projectRoot, manifestPointer, and scanId are required");
+  }
+  const { content, row } = await hydratePointer(projectRoot, manifestPointer);
+  const payload = JSON.parse(content.toString("utf8"));
+  if (row.artifactName === "artifact_manifest") {
+    const manifest = payload;
+    const analysisEntry = manifest.artifacts.find((a) => a.name === "analysis" || a.name === "analysis.index");
+    if (!analysisEntry?.indexes?.startHere) {
+      throw new Error("Manifest has no analysis.index entry \u2014 rescan to regenerate");
+    }
+    const { content: indexContent } = await hydratePointer(projectRoot, analysisEntry.indexes.startHere);
+    const index = JSON.parse(indexContent.toString("utf8"));
+    const result = {
+      startHere: index.startHere.slice(0, 5),
+      schemaVersion: index.schemaVersion,
+      scanId: index.scanId
+    };
+    return await applyBudgetGuard(projectRoot, scanId, "get_start_here_result", result);
+  }
+  if (row.artifactName === "analysis.index") {
+    const result = {
+      startHere: payload.startHere.slice(0, 5),
+      schemaVersion: payload.schemaVersion,
+      scanId: payload.scanId
+    };
+    return await applyBudgetGuard(projectRoot, scanId, "get_start_here_result", result);
+  }
+  throw new Error(`Unsupported artifact type for get_start_here: ${row.artifactName}`);
+}
+
+// dist/mcp/tools/hydration/get_project_summary.js
+var getProjectSummaryTool = {
+  name: "get_project_summary",
+  description: "Returns high-level project metrics from a scan manifest pointer: file counts, pillar summary, stack. Token-safe. Pointer must be valid and unexpired.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectRoot: { type: "string", description: "Absolute project root" },
+      manifestPointer: { type: "string", description: "Pointer ID for the scan manifest" },
+      scanId: { type: "string", description: "Current scan ID for budget pointer registration" }
+    },
+    required: ["projectRoot", "manifestPointer", "scanId"]
+  }
+};
+async function handleGetProjectSummary(args) {
+  const projectRoot = args.projectRoot;
+  const manifestPointer = args.manifestPointer;
+  const scanId = args.scanId;
+  if (!projectRoot || !manifestPointer || !scanId) {
+    throw new Error("projectRoot, manifestPointer, and scanId are required");
+  }
+  const { content, row } = await hydratePointer(projectRoot, manifestPointer);
+  const payload = JSON.parse(content.toString("utf8"));
+  if (row.artifactName === "artifact_manifest") {
+    const manifest = payload;
+    const analysisEntry = manifest.artifacts.find((a) => a.name === "analysis" && a.indexes?.startHere);
+    let indexData = {};
+    if (analysisEntry?.indexes?.startHere) {
+      const { content: ic } = await hydratePointer(projectRoot, analysisEntry.indexes.startHere);
+      indexData = JSON.parse(ic.toString("utf8"));
+    }
+    const result = {
+      scanId: manifest.scanId,
+      generatedAt: manifest.generatedAt,
+      artifactCount: manifest.artifacts.length,
+      totalArtifactBytes: manifest.artifacts.reduce((s, a) => s + (a.sizeBytes ?? 0), 0),
+      startHere: indexData.startHere,
+      topHeat: indexData.topHeat,
+      pillarSummary: indexData.pillarSummary,
+      totalFiles: indexData.totalFiles,
+      realSourceFiles: indexData.realSourceFiles
+    };
+    return await applyBudgetGuard(projectRoot, scanId, "get_project_summary_result", result);
+  }
+  if (row.artifactName === "analysis.index") {
+    const result = {
+      scanId: payload.scanId,
+      startHere: payload.startHere,
+      topHeat: payload.topHeat,
+      pillarSummary: payload.pillarSummary,
+      totalFiles: payload.totalFiles,
+      realSourceFiles: payload.realSourceFiles
+    };
+    return await applyBudgetGuard(projectRoot, scanId, "get_project_summary_result", result);
+  }
+  throw new Error(`Unsupported artifact type for get_project_summary: ${row.artifactName}`);
+}
+
+// dist/mcp/tools/hydration/get_evidence_slice.js
+var getEvidenceSliceTool = {
+  name: "get_evidence_slice",
+  description: "Raw fallback: returns a line-range slice from a blob artifact. Pointer must be valid and unexpired. Output is budgeted.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectRoot: { type: "string", description: "Absolute project root" },
+      pointerId: { type: "string", description: "Pointer ID for the target artifact" },
+      startLine: { type: "number", description: "Inclusive start line (1-based)" },
+      endLine: { type: "number", description: "Inclusive end line (1-based). Capped at startLine+200." },
+      scanId: { type: "string", description: "Current scan ID for budget pointer registration" }
+    },
+    required: ["projectRoot", "pointerId", "startLine", "endLine", "scanId"]
+  }
+};
+async function handleGetEvidenceSlice(args) {
+  const projectRoot = args.projectRoot;
+  const pointerId = args.pointerId;
+  const startLine = Number(args.startLine);
+  const endLine = Math.min(Number(args.endLine), startLine + 200);
+  const scanId = args.scanId;
+  if (!projectRoot || !pointerId || !scanId) {
+    throw new Error("projectRoot, pointerId, startLine, endLine, and scanId are required");
+  }
+  const { content, row } = await hydratePointer(projectRoot, pointerId);
+  const rawText = content.toString("utf8");
+  const scope = SessionScope.get();
+  if (scope && (row.artifactName === "file_read" || row.artifactName === "file_skeleton")) {
+    try {
+      const parsed = JSON.parse(rawText);
+      if (parsed.filePath) {
+        SessionScope.enforce(parsed.filePath);
+      }
+    } catch (e) {
+      if (e.name === "ScopeViolation")
+        throw e;
+    }
+  }
+  const lines = rawText.split("\n");
+  const sliced = lines.slice(startLine - 1, endLine);
+  const result = {
+    pointerId,
+    artifactName: row.artifactName,
+    startLine,
+    endLine,
+    totalLines: lines.length,
+    slice: sliced
+  };
+  return await applyBudgetGuard(projectRoot, scanId, "evidence_slice", result);
+}
+
 // dist/mcp/server.js
 var ALL_TOOLS = [
   scanProjectTool,
@@ -4297,7 +5531,21 @@ var ALL_TOOLS = [
   getStrategicOverviewTool,
   inspectPillarTool,
   getWildDiscoveriesTool,
-  markStaleTool
+  markStaleTool,
+  // Phase 2: Skeletons + Hydration
+  getFileSkeletonTool,
+  readFileTool,
+  getStartHereTool,
+  getProjectSummaryTool,
+  getEvidenceSliceTool,
+  // Phase 3: Delegation & Proof
+  createWorkOrderTool,
+  spawnWorkerTool,
+  applyPatchTool,
+  submitReceiptTool,
+  // Phase 4: Scope & Escalation
+  setSessionScopeTool,
+  yieldForScopeExpansionTool
 ];
 var TOOL_HANDLERS = {
   scan_project: handleScanProject,
@@ -4309,7 +5557,21 @@ var TOOL_HANDLERS = {
   get_strategic_overview: handleGetStrategicOverview,
   inspect_pillar: handleInspectPillar,
   get_wild_discoveries: handleGetWildDiscoveries,
-  mark_stale: handleMarkStale
+  mark_stale: handleMarkStale,
+  // Phase 2
+  get_file_skeleton: handleGetFileSkeleton,
+  read_file: handleReadFile,
+  get_start_here: handleGetStartHere,
+  get_project_summary: handleGetProjectSummary,
+  get_evidence_slice: handleGetEvidenceSlice,
+  // Phase 3
+  create_work_order: handleCreateWorkOrder,
+  spawn_worker: handleSpawnWorker,
+  apply_patch: handleApplyPatch,
+  submit_receipt: handleSubmitReceipt,
+  // Phase 4
+  set_session_scope: handleSetSessionScope,
+  yield_for_scope_expansion: handleYieldForScopeExpansion
 };
 async function startMCPServer(options = {}) {
   await initParser2();
@@ -4453,10 +5715,210 @@ async function exportCommand(projectRoot, options) {
   console.error("[vibe-splain] Export complete.");
 }
 
+// dist/commands/gc.js
+import { join as join21 } from "path";
+import { rm as rm2, readdir as readdir2 } from "fs/promises";
+var DEFAULT_KEEP_SCANS = 3;
+async function gcCommand(projectRoot, opts = {}) {
+  const root = projectRoot ?? process.cwd();
+  const keepScans = opts.keepScans ?? DEFAULT_KEEP_SCANS;
+  console.error(`[vibe-splain gc] Running GC on ${root} (keeping last ${keepScans} scans)`);
+  const pointerStore = PointerStore.open(root);
+  const blobStore = new BlobStore(root);
+  const allScanIds = pointerStore.listAllScanIds();
+  console.error(`[vibe-splain gc] Found ${allScanIds.length} scans`);
+  const sorted = [...allScanIds].sort().reverse();
+  const keepIds = sorted.slice(0, keepScans);
+  const deleteIds = sorted.slice(keepScans);
+  if (deleteIds.length === 0) {
+    console.error("[vibe-splain gc] Nothing to collect");
+    return;
+  }
+  const keptPointers = keepIds.flatMap((id) => pointerStore.listPointersByScan(id));
+  const referencedBlobs = new Set(keptPointers.map((p) => p.blobPath));
+  const deleted = await pointerStore.gcScanPointers(keepIds);
+  console.error(`[vibe-splain gc] Deleted ${deleted} pointer rows`);
+  const allBlobs = await blobStore.listBlobPaths();
+  let blobsDeleted = 0;
+  for (const blobPath of allBlobs) {
+    if (!referencedBlobs.has(blobPath)) {
+      try {
+        await rm2(blobPath);
+        blobsDeleted++;
+      } catch {
+      }
+    }
+  }
+  console.error(`[vibe-splain gc] Deleted ${blobsDeleted} unreferenced blobs`);
+  const tmpDir = join21(root, ".vibe-splainer", "tmp");
+  try {
+    const tmpFiles = await readdir2(tmpDir);
+    for (const f of tmpFiles) {
+      await rm2(join21(tmpDir, f), { force: true });
+    }
+    console.error(`[vibe-splain gc] Cleaned ${tmpFiles.length} tmp files`);
+  } catch {
+  }
+  console.error("[vibe-splain gc] Done");
+}
+
+// dist/commands/bundle.js
+import { join as join22 } from "path";
+import { writeFile as writeFile10, mkdir as mkdir9, copyFile, rm as rm3 } from "fs/promises";
+import { existsSync as existsSync7 } from "fs";
+import * as tar from "tar";
+async function bundleCommand(scanId, opts = {}) {
+  const root = opts.projectRoot ?? process.cwd();
+  const outputPath = opts.output ?? join22(root, `vibe-bundle-${scanId}.tar.gz`);
+  console.error(`[vibe-splain bundle] Bundling scan ${scanId} from ${root}`);
+  const pointerStore = PointerStore.open(root);
+  const blobStore = new BlobStore(root);
+  const pointers = pointerStore.listPointersByScan(scanId);
+  if (pointers.length === 0) {
+    throw new Error(`No pointers found for scanId "${scanId}"`);
+  }
+  const stagingDir = join22(root, ".vibe-splainer", "tmp", `bundle-stage-${scanId}`);
+  const blobsStageDir = join22(stagingDir, "blobs");
+  await mkdir9(blobsStageDir, { recursive: true });
+  try {
+    const bundleManifest = {
+      schemaVersion: "1.0.0",
+      scanId,
+      exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      projectRoot: root,
+      pointers: pointers.map((p) => ({
+        pointerId: p.pointerId,
+        scanId: p.scanId,
+        artifactName: p.artifactName,
+        contentHash: p.contentHash,
+        blobFile: `blobs/${p.contentHash.replace("sha256:", "sha256_")}`,
+        schemaVersion: p.schemaVersion,
+        createdAt: p.createdAt,
+        expiresAt: p.expiresAt
+      }))
+    };
+    await writeFile10(join22(stagingDir, "bundle-manifest.json"), JSON.stringify(bundleManifest, null, 2), "utf8");
+    const seen = /* @__PURE__ */ new Set();
+    for (const p of pointers) {
+      const hex = p.contentHash.replace("sha256:", "");
+      if (seen.has(hex))
+        continue;
+      seen.add(hex);
+      const srcPath = p.blobPath;
+      if (!existsSync7(srcPath)) {
+        console.error(`[vibe-splain bundle] Warning: blob missing for ${p.pointerId}: ${srcPath}`);
+        continue;
+      }
+      await copyFile(srcPath, join22(blobsStageDir, `sha256_${hex}`));
+    }
+    await tar.create({
+      gzip: true,
+      file: outputPath,
+      cwd: stagingDir,
+      portable: true
+    }, ["."]);
+    console.error(`[vibe-splain bundle] Bundle written: ${outputPath}`);
+    console.error(`[vibe-splain bundle] ${pointers.length} pointers, ${seen.size} blobs`);
+  } finally {
+    await rm3(stagingDir, { recursive: true, force: true });
+  }
+}
+
+// dist/commands/importBundle.js
+import { join as join23 } from "path";
+import { readFile as readFile15, mkdir as mkdir10, rm as rm4 } from "fs/promises";
+import { existsSync as existsSync8 } from "fs";
+import * as tar2 from "tar";
+import { createHash as createHash6 } from "crypto";
+async function importBundleCommand(tarballPath, opts = {}) {
+  const root = opts.projectRoot ?? process.cwd();
+  const namespace = opts.namespace ?? `imported_${Date.now()}`;
+  console.error(`[vibe-splain import] Importing ${tarballPath} into ${root} (namespace: ${namespace})`);
+  if (!existsSync8(tarballPath)) {
+    throw new Error(`Tarball not found: ${tarballPath}`);
+  }
+  const extractDir = join23(root, ".vibe-splainer", "tmp", `import-${namespace}`);
+  await mkdir10(extractDir, { recursive: true });
+  try {
+    await tar2.extract({
+      file: tarballPath,
+      cwd: extractDir
+    });
+    const manifestPath = join23(extractDir, "bundle-manifest.json");
+    if (!existsSync8(manifestPath)) {
+      throw new Error("Invalid bundle: missing bundle-manifest.json");
+    }
+    const manifestRaw = await readFile15(manifestPath, "utf8");
+    const manifest = JSON.parse(manifestRaw);
+    if (manifest.schemaVersion !== "1.0.0") {
+      throw new Error(`Unsupported bundle schema version: ${manifest.schemaVersion}`);
+    }
+    const blobStore = new BlobStore(root);
+    const pointerStore = PointerStore.open(root);
+    await blobStore.ensureDirs();
+    let imported = 0;
+    let hashErrors = 0;
+    for (const entry of manifest.pointers) {
+      const blobSrcPath = join23(extractDir, entry.blobFile);
+      if (!existsSync8(blobSrcPath)) {
+        console.error(`[vibe-splain import] Missing blob for pointer ${entry.pointerId}: ${entry.blobFile}`);
+        hashErrors++;
+        continue;
+      }
+      const content = await readFile15(blobSrcPath);
+      const actualHash = `sha256:${createHash6("sha256").update(content).digest("hex")}`;
+      if (actualHash !== entry.contentHash) {
+        console.error(`[vibe-splain import] Hash mismatch for ${entry.pointerId}: expected ${entry.contentHash}, got ${actualHash}`);
+        hashErrors++;
+        continue;
+      }
+      const { blobPath } = await blobStore.writeAtomic(content);
+      const namespacedPointerId = `${namespace}::${entry.pointerId}`;
+      const namespacedScanId = `${namespace}::${entry.scanId}`;
+      await pointerStore.insertPointer({
+        pointerId: namespacedPointerId,
+        scanId: namespacedScanId,
+        artifactName: entry.artifactName,
+        contentHash: entry.contentHash,
+        blobPath,
+        schemaVersion: entry.schemaVersion,
+        createdAt: entry.createdAt,
+        expiresAt: entry.expiresAt
+      });
+      imported++;
+    }
+    if (hashErrors > 0) {
+      console.error(`[vibe-splain import] Warning: ${hashErrors} blobs failed hash verification and were skipped`);
+    }
+    console.error(`[vibe-splain import] Imported ${imported}/${manifest.pointers.length} pointers under namespace "${namespace}"`);
+    console.error(`[vibe-splain import] Original scanId: ${manifest.scanId} \u2192 namespaced as: ${namespace}::${manifest.scanId}`);
+  } finally {
+    await rm4(extractDir, { recursive: true, force: true });
+  }
+}
+
 // dist/index.js
 var program = new Command();
-program.name("vibe-splain").description("Architectural dossier engine for vibe-coded projects").version("3.0.0");
+program.name("vibe-splain").description("Architectural dossier engine for vibe-coded projects").version("3.2.0");
 program.command("install").description("Patch coding agent MCP config files to register vibe-splain").action(installCommand);
 program.command("serve").description("Start the MCP server (called by the coding agent, not by you)").option("--format <format>", "Export format (html, markdown, etc.)").option("--budget <budget>", "Token budget for markdown").option("--scope <scope>", "Scope for export").action((options) => serveCommand(options));
 program.command("export [projectRoot]").description("Manually trigger bundle generation").option("--format <format>", "Export format (html, markdown, etc.)").option("--budget <budget>", "Token budget for markdown").option("--scope <scope>", "Scope for export").action(exportCommand);
+program.command("gc [projectRoot]").description("Garbage-collect old scan artifacts, keeping the last N scans").option("--keep-scans <n>", "Number of scans to keep (default: 3)", "3").action((projectRoot, options) => {
+  gcCommand(projectRoot, { keepScans: parseInt(options.keepScans, 10) }).catch((err) => {
+    console.error("[vibe-splain gc] Error:", err.message);
+    process.exit(1);
+  });
+});
+program.command("bundle <scanId>").description("Bundle a scan into a portable vibe-bundle.tar.gz").option("--output <path>", "Output tarball path").option("--project-root <path>", "Project root (default: cwd)").action((scanId, options) => {
+  bundleCommand(scanId, { output: options.output, projectRoot: options.projectRoot }).catch((err) => {
+    console.error("[vibe-splain bundle] Error:", err.message);
+    process.exit(1);
+  });
+});
+program.command("import <tarball>").description("Import a vibe-bundle.tar.gz into the local pointer store").option("--namespace <ns>", "Bundle namespace alias (default: imported_<timestamp>)").option("--project-root <path>", "Project root (default: cwd)").action((tarball, options) => {
+  importBundleCommand(tarball, { namespace: options.namespace, projectRoot: options.projectRoot }).catch((err) => {
+    console.error("[vibe-splain import] Error:", err.message);
+    process.exit(1);
+  });
+});
 program.parse();