@coderule/mcp 2.0.3 → 2.2.0

package/dist/mcp-cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import fs5 from 'fs/promises';
-import path2 from 'path';
+import fs5, { mkdir, writeFile } from 'fs/promises';
+import path2, { dirname } from 'path';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createHash } from 'crypto';
 import envPaths from 'env-paths';
@@ -527,7 +527,10 @@ var FilesRepo = class {
       `UPDATE files
      SET content_sha256 = ?, service_file_hash = ?, hash_state = 'clean',
          hash_owner = NULL, hash_lease_expires_at = NULL, hash_started_at = NULL
-     WHERE id = ?`
+     WHERE id = ?
+       AND hash_state = 'hashing'
+       AND hash_owner = ?
+       AND hash_started_at = ?`
     );
     this.requeueExpiredHashingStmt = this.db.prepare(
       `UPDATE files
@@ -658,13 +661,30 @@ var FilesRepo = class {
     tx(ids);
   }
   applyHashResults(results) {
-    if (!results.length) return;
+    if (!results.length) return 0;
+    let applied = 0;
     const tx = this.db.transaction((batch) => {
-      for (const { id, contentSha256, serviceFileHash } of batch) {
-        this.applyHashesStmt.run(contentSha256, serviceFileHash, id);
+      for (const {
+        id,
+        contentSha256,
+        serviceFileHash,
+        hashOwner,
+        hashStartedAt
+      } of batch) {
+        const result = this.applyHashesStmt.run(
+          contentSha256,
+          serviceFileHash,
+          id,
+          hashOwner,
+          hashStartedAt
+        );
+        if ((result.changes ?? 0) > 0) {
+          applied += 1;
+        }
       }
     });
     tx(results);
+    return applied;
   }
   getCleanFilesForSnapshot() {
     return this.selectCleanSnapshotStmt.all();
@@ -714,7 +734,7 @@ var Outbox = class {
     this.log = logger2.child({ scope: "outbox" });
     this.queue = new Qulite(db, {
       logger: this.log,
-      defaultLeaseMs: 3e4,
+      defaultLeaseMs: 6e5,
       defaultMaxAttempts: 10
     });
     this.markKindStmt = db.prepare(
@@ -772,7 +792,7 @@ var Outbox = class {
       this.log.debug({ rootId }, "Enqueued heartbeat job");
     }
   }
-  claimFsControlJob(leaseOwner, leaseMs = 3e4) {
+  claimFsControlJob(leaseOwner, leaseMs = 6e5) {
     return this.queue.claimNext({ type: "fs_control", leaseOwner, leaseMs });
   }
   ack(jobId, leaseOwner) {
@@ -1088,7 +1108,9 @@ var Hasher = class {
         successes.push({
           id: record.id,
           contentSha256: result.contentSha256,
-          serviceFileHash: result.serviceFileHash
+          serviceFileHash: result.serviceFileHash,
+          hashOwner: record.hash_owner ?? this.ownerId,
+          hashStartedAt: record.hash_started_at ?? 0
         });
       } catch (error) {
         if (error?.code === "ENOENT") {
@@ -1247,6 +1269,42 @@ async function runInventory(opts) {
 async function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+var SnapshotStaleError = class extends Error {
+  constructor(message = "snapshot became stale") {
+    super(message);
+    this.name = "SnapshotStaleError";
+  }
+};
+function assertNotStale(opts) {
+  if (opts?.isStale?.()) {
+    throw new SnapshotStaleError();
+  }
+}
+function assertBeforeDeadline(opts) {
+  if (opts?.deadlineMs !== void 0 && Date.now() >= opts.deadlineMs) {
+    throw new Error("snapshot publish deadline exceeded");
+  }
+}
+function assertValid(opts) {
+  assertNotStale(opts);
+  assertBeforeDeadline(opts);
+}
+function withDeadline(promise, opts) {
+  if (opts?.deadlineMs === void 0) return promise;
+  const remaining = opts.deadlineMs - Date.now();
+  if (remaining <= 0) {
+    return Promise.reject(new Error("snapshot publish deadline exceeded"));
+  }
+  return Promise.race([
+    promise,
+    new Promise(
+      (_, reject) => setTimeout(
+        () => reject(new Error("snapshot publish deadline exceeded")),
+        remaining
+      )
+    )
+  ]);
+}
 function computeSnapshot(filesRepo) {
   const files = filesRepo.getCleanFilesForSnapshot();
   const hashes = files.map((file) => file.service_file_hash).filter((hash) => typeof hash === "string");
@@ -1262,12 +1320,17 @@ function computeSnapshot(filesRepo) {
     totalSize
   };
 }
-async function withRetries(op, logger2, context, maxAttempts) {
+async function withRetries(op, logger2, context, maxAttempts, opts) {
   let attempt = 0;
   while (true) {
+    assertValid(opts);
     try {
-      return await op();
+      return await withDeadline(op(), opts);
     } catch (err) {
+      if (err instanceof SnapshotStaleError) throw err;
+      if (typeof err?.message === "string" && err.message.includes("deadline exceeded")) {
+        throw err;
+      }
       attempt += 1;
       if (attempt >= maxAttempts) {
         logger2.error(
@@ -1285,7 +1348,14 @@ async function withRetries(op, logger2, context, maxAttempts) {
     }
   }
 }
-async function uploadMissing(rootPath, missing, syncClient, logger2, maxAttempts, chunkSize = 1) {
+function computeServiceFileHash(relPath, content) {
+  const hash = createHash("sha256");
+  hash.update(relPath);
+  hash.update("\n");
+  hash.update(content);
+  return hash.digest("hex");
+}
+async function uploadMissing(rootPath, missing, syncClient, logger2, maxAttempts, chunkSize = 1, opts) {
   if (!missing || missing.length === 0) return;
   const total = missing.length;
   const chunks = [];
@@ -1293,17 +1363,36 @@ async function uploadMissing(rootPath, missing, syncClient, logger2, maxAttempts
     chunks.push(missing.slice(i, i + chunkSize));
   }
   for (let idx = 0; idx < chunks.length; idx++) {
+    assertValid(opts);
     const list = chunks[idx];
     const map = /* @__PURE__ */ new Map();
     for (const missingFile of list) {
       const absPath = path2.join(rootPath, missingFile.file_path);
       try {
         const buffer = await fs5.readFile(absPath);
+        const serviceHash = computeServiceFileHash(
+          missingFile.file_path,
+          buffer
+        );
+        if (serviceHash !== missingFile.file_hash) {
+          logger2.warn(
+            {
+              relPath: missingFile.file_path,
+              expected: missingFile.file_hash,
+              got: serviceHash
+            },
+            "File content changed during upload; snapshot is stale"
+          );
+          throw new SnapshotStaleError(
+            `file hash mismatch for ${missingFile.file_path}`
+          );
+        }
         map.set(missingFile.file_hash, {
           path: missingFile.file_path,
           content: buffer
         });
       } catch (error) {
+        if (error instanceof SnapshotStaleError) throw error;
         logger2.warn(
           { err: error, relPath: missingFile.file_path },
           "Failed to read missing file content"
@@ -1311,6 +1400,7 @@ async function uploadMissing(rootPath, missing, syncClient, logger2, maxAttempts
       }
     }
     if (map.size === 0) continue;
+    assertValid(opts);
     await withRetries(
       () => syncClient.uploadFileContent(map),
       logger2,
@@ -1320,65 +1410,76 @@ async function uploadMissing(rootPath, missing, syncClient, logger2, maxAttempts
         chunks: chunks.length,
         files: map.size
       },
-      maxAttempts
+      maxAttempts,
+      opts
     );
   }
 }
-async function ensureSnapshotCreated(rootPath, computation, syncClient, logger2, options) {
+async function ensureSnapshotCreated(rootPath, computation, syncClient, logger2, opts) {
   const { snapshotHash, files } = computation;
-  const maxAttempts = options?.maxAttempts ?? 5;
-  const uploadChunkSize = options?.uploadChunkSize ?? 1;
+  const maxAttempts = opts?.maxAttempts ?? 5;
+  const uploadChunkSize = opts?.uploadChunkSize ?? 1;
+  assertValid(opts);
   let status = await withRetries(
     () => syncClient.checkSnapshotStatus(snapshotHash),
     logger2,
     { op: "checkSnapshotStatus", snapshotHash },
-    maxAttempts
+    maxAttempts,
+    opts
   );
   if (status.status === "READY") {
     logger2.info({ snapshotHash }, "Snapshot already READY");
     return;
   }
-  if (status.status === "NOT_FOUND" || status.status === "MISSING_CONTENT") {
-    status = await withRetries(
-      () => syncClient.createSnapshot(snapshotHash, files),
-      logger2,
-      { op: "createSnapshot", snapshotHash },
-      maxAttempts
-    );
-  }
-  if (status.status === "MISSING_CONTENT" && status.missing_files?.length) {
-    logger2.info(
-      { missing: status.missing_files.length },
-      "Uploading missing file content"
-    );
-    await uploadMissing(
-      rootPath,
-      status.missing_files,
-      syncClient,
-      logger2,
-      maxAttempts,
-      uploadChunkSize
-    );
-    status = await withRetries(
-      () => syncClient.createSnapshot(snapshotHash, files),
-      logger2,
-      { op: "createSnapshot", snapshotHash },
-      maxAttempts
-    );
-  }
   let attempt = 0;
   while (status.status !== "READY") {
+    assertValid(opts);
     if (status.status === "FAILED") {
       throw new Error(`Snapshot failed processing: ${JSON.stringify(status)}`);
     }
+    if (status.status === "NOT_FOUND" || status.status === "MISSING_CONTENT") {
+      status = await withRetries(
+        () => syncClient.createSnapshot(snapshotHash, files),
+        logger2,
+        { op: "createSnapshot", snapshotHash },
+        maxAttempts,
+        opts
+      );
+    }
+    if (status.status === "MISSING_CONTENT" && status.missing_files?.length) {
+      logger2.info(
+        { missing: status.missing_files.length },
+        "Uploading missing file content"
+      );
+      await uploadMissing(
+        rootPath,
+        status.missing_files,
+        syncClient,
+        logger2,
+        maxAttempts,
+        uploadChunkSize,
+        opts
+      );
+      status = await withRetries(
+        () => syncClient.createSnapshot(snapshotHash, files),
+        logger2,
+        { op: "createSnapshot", snapshotHash },
+        maxAttempts,
+        opts
+      );
+      continue;
+    }
+    if (status.status === "READY") break;
     const delay = Math.min(5e3, 1e3 * Math.max(1, 2 ** attempt));
     await sleep(delay);
     attempt += 1;
+    assertValid(opts);
     status = await withRetries(
       () => syncClient.checkSnapshotStatus(snapshotHash),
       logger2,
       { op: "checkSnapshotStatus", snapshotHash },
-      maxAttempts
+      maxAttempts,
+      opts
     );
   }
   logger2.info({ snapshotHash }, "Snapshot READY");
@@ -1545,12 +1646,14 @@ async function sendHeartbeat(rootId, snapshotsRepo, syncClient, logger2) {
 // src/service/State.ts
 var ServiceState = class {
   constructor() {
+    this.changeSeq = 0;
     this.lastChangeAt = Date.now();
     this.lastSnapshotReadyAt = Date.now();
     this.lastHeartbeatEnqueuedAt = 0;
   }
   updateChange(timestamp = Date.now()) {
     this.lastChangeAt = timestamp;
+    this.changeSeq += 1;
   }
   updateSnapshotReady(timestamp = Date.now()) {
     this.lastSnapshotReadyAt = timestamp;
@@ -1576,6 +1679,7 @@ function computeBackoff(attempts) {
   const delay = 1e3 * 2 ** base;
   return Math.min(delay, 6e4);
 }
+var PUBLISH_MAX_MS = 5 * 6e4;
 async function readSymlinkTarget2(absPath) {
   try {
     return await fs5.readlink(absPath);
@@ -1854,9 +1958,10 @@ var ServiceRunner = class {
     if (this.runtime.filesRepo.countByState("dirty") > 0 || this.runtime.filesRepo.countByState("hashing") > 0) {
       const delay = computeBackoff(job.attempts);
       this.runtime.outbox.retry(job.id, this.fsControlLeaseOwner, delay);
-      await sleep2(200);
       return;
     }
+    const publishSeq = this.state.changeSeq;
+    const isStale = () => this.state.changeSeq !== publishSeq || this.runtime.filesRepo.countByState("dirty") > 0 || this.runtime.filesRepo.countByState("hashing") > 0;
     try {
       const result = await publishSnapshot(
         this.runtime.config.rootPath,
@@ -1866,17 +1971,40 @@ var ServiceRunner = class {
         log,
         {
           maxAttempts: this.runtime.config.maxSnapshotAttempts,
-          uploadChunkSize: this.runtime.config.uploadChunkSize
+          uploadChunkSize: this.runtime.config.uploadChunkSize,
+          deadlineMs: Date.now() + PUBLISH_MAX_MS,
+          isStale
         }
       );
-      this.runtime.outbox.ack(job.id, this.fsControlLeaseOwner);
+      const acked = this.runtime.outbox.ack(job.id, this.fsControlLeaseOwner);
+      if (!acked) {
+        log.warn(
+          { jobId: job.id },
+          "Snapshot job ack failed (lease may have expired)"
+        );
+      }
       this.state.updateSnapshotReady(result.createdAt);
       log.info({ snapshotHash: result.snapshotHash }, "Snapshot job completed");
+      if (this.runtime.filesRepo.countByState("dirty") > 0 || this.runtime.filesRepo.countByState("hashing") > 0) {
+        this.runtime.outbox.enqueueSnapshot(this.runtime.config.rootId, 0);
+        return;
+      }
+      const nowHash = computeSnapshot(this.runtime.filesRepo).snapshotHash;
+      if (nowHash !== result.snapshotHash) {
+        this.runtime.outbox.enqueueSnapshot(this.runtime.config.rootId, 0);
+      }
     } catch (error) {
+      if (error instanceof SnapshotStaleError) {
+        log.debug(
+          { err: error },
+          "Snapshot publish aborted (stale); quick retry"
+        );
+        this.runtime.outbox.retry(job.id, this.fsControlLeaseOwner, 250);
+        return;
+      }
       log.warn({ err: error }, "Snapshot job failed");
       const delay = computeBackoff(job.attempts);
       this.runtime.outbox.retry(job.id, this.fsControlLeaseOwner, delay);
-      await sleep2(delay);
     }
   }
   async handleHeartbeatJob(job, log) {
@@ -2085,33 +2213,20 @@ function createMcpServer({
   async function sleep3(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
-  async function waitForLocalSnapshot(deadlineMs) {
-    let latest = runtime.snapshotsRepo.getLatest();
-    while (!latest && Date.now() < deadlineMs) {
-      await sleep3(250);
-      latest = runtime.snapshotsRepo.getLatest();
-    }
-    return latest;
+  function isLocalStable() {
+    return runtime.filesRepo.countByState("dirty") === 0 && runtime.filesRepo.countByState("hashing") === 0;
   }
-  async function waitForServerReady(initialHash, deadlineMs) {
-    let currentHash = initialHash;
-    while (Date.now() < deadlineMs) {
-      try {
-        const status = await runtime.clients.sync.checkSnapshotStatus(currentHash);
-        if (status.status === "READY") {
-          return currentHash;
-        }
-        if (status.status === "FAILED") {
-        }
-      } catch {
-      }
-      await sleep3(500);
-      const latest = runtime.snapshotsRepo.getLatest();
-      if (latest && latest.snapshot_hash !== currentHash) {
-        currentHash = latest.snapshot_hash;
-      }
+  async function withDeadline2(promise, deadlineMs) {
+    const remaining = deadlineMs - Date.now();
+    if (remaining <= 0) {
+      throw new Error("deadline exceeded");
     }
-    return void 0;
+    return Promise.race([
+      promise,
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("deadline exceeded")), remaining)
+      )
+    ]);
   }
   const server = new McpServer({
     name: SERVER_NAME,
@@ -2145,20 +2260,26 @@ function createMcpServer({
       title: "Semantic Code Retrieval",
       description: "USE THIS before code exploration. Graph-based RAG for semantic code search using AST relationships and embeddings. Returns 30-50 code segments with file paths and line numbers. After initial query, you may query again with refined keywords or use conventional tools (Read, Glob, Grep) for specific files.",
       inputSchema: {
-        query: z.string().min(1, "Query text is required").describe(`Keyword-rich query using technical terms (NOT natural language questions).
+        query: z.string().min(1, "Query text is required").describe(`Short docstring-style description of what the code does + specific technical terms and identifiers (NOT natural language questions, NOT bare keyword lists).
 
-STRATEGY: Use space-separated technical keywords that describe what you're looking for.
+STRATEGY: Start with a mini-docstring (what the code does), then append concrete identifiers, API names, error types, and domain terms.
 
 \u2705 GOOD EXAMPLES:
-- "JWT authentication middleware token validation security handler FastAPI"
-- "file indexing worker celery queue job AST parser embedding chunker"
-- "database schema SQLAlchemy model migration table column relationship"
-- "error handling exception try catch logging traceback"
+- "Validate JWT access token and extract user claims FastAPI dependency AuthMiddleware jose jwt decode RS256 audience issuer"
+- "Index repository files into embedding store Celery worker chunker AST parse imports calls graph propagate batch upsert vector_index"
+- "Create Alembic migration for SQLAlchemy relationship add foreign key backfill existing rows cascade ondelete constraint naming"
+- "Capture exception with traceback and structured context logging logger.exception request_id correlation_id retryable errors"
+- "Load cache from file using shelve.open handle OSError fallback recreate cache file path validation"
+- "Find call sites of verify_jwt decode_jwt get_current_user where used FastAPI router dependency tests pytest"
 
 \u274C BAD EXAMPLES:
 - "How does authentication work?" (natural language question)
 - "Show me the login code" (conversational)
 - "auth" (too vague, needs more context)
+- "JWT authentication middleware token validation security handler FastAPI" (bare keyword list without intent \u2014 add a docstring prefix describing what the code does)
+
+NON-ENGLISH QUERIES: Translate to English before querying.
+- "validate JWT signature and extract claims FastAPI jose RS256 issuer audience"
 
 RETRIEVAL MECHANISM:
 Combines multiple strategies: Seeds (semantic similarity), Flood (AST graph propagation through imports/calls/inheritance), Neighbors (adjacent chunks), and Calls (function relationships).
@@ -2186,53 +2307,216 @@ WHEN TO USE THIS TOOL:
       budgetTokens
     }) => {
       const deadline = Date.now() + runtime.config.maxQueryWaitMs;
-      const latest = await waitForLocalSnapshot(deadline);
-      if (!latest) {
-        const statusText = formatStatus(
+      while (Date.now() < deadline) {
+        if (isLocalStable()) break;
+        await sleep3(250);
+      }
+      if (!isLocalStable()) {
+        const statusText2 = formatStatus(
           await collectIndexingStatus(runtime, runner)
         );
-        const text = `Indexer not ready. Current status:
+        const text2 = `Indexer not ready (local hashing/dirty). Current status:
 
-${statusText}`;
-        return { content: [{ type: "text", text }] };
+${statusText2}`;
+        return { content: [{ type: "text", text: text2 }] };
       }
-      const readyHash = await waitForServerReady(
-        latest.snapshot_hash,
-        deadline
+      let currentHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+      let lastStatus;
+      while (Date.now() < deadline) {
+        if (!isLocalStable()) {
+          while (Date.now() < deadline) {
+            if (isLocalStable()) break;
+            await sleep3(250);
+          }
+          if (!isLocalStable()) break;
+          currentHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+          continue;
+        }
+        try {
+          const status = await withDeadline2(
+            runtime.clients.sync.checkSnapshotStatus(currentHash),
+            deadline
+          );
+          lastStatus = status.status;
+          if (status.status === "READY") {
+            const effectiveBudget = Math.max(100, budgetTokens ?? 1e4);
+            try {
+              const result = await withDeadline2(
+                runtime.clients.retrieval.query(
+                  currentHash,
+                  query,
+                  effectiveBudget,
+                  { formatter: runtime.config.retrievalFormatter }
+                ),
+                deadline
+              );
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: result.formatted_output ?? "(no formatted output)"
+                  }
+                ]
+              };
+            } catch (error) {
+              const message = error instanceof Error ? error.message : "Unknown retrieval error";
+              runtime.logger.error({ err: error }, "Retrieval query failed");
+              return {
+                content: [
+                  { type: "text", text: `Retrieval error: ${message}` }
+                ],
+                isError: true
+              };
+            }
+          }
+          if (status.status === "FAILED") {
+            while (Date.now() < deadline) {
+              if (isLocalStable()) break;
+              await sleep3(250);
+            }
+            if (!isLocalStable()) break;
+            currentHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+            continue;
+          }
+          runtime.outbox.enqueueSnapshot(runtime.config.rootId, 0);
+        } catch {
+        }
+        const newHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+        if (newHash !== currentHash) {
+          currentHash = newHash;
+          continue;
+        }
+        await sleep3(500);
+      }
+      const statusText = formatStatus(
+        await collectIndexingStatus(runtime, runner)
       );
-      if (!readyHash) {
-        const statusText = formatStatus(
-          await collectIndexingStatus(runtime, runner)
-        );
-        const text = `Snapshot not ready on server. Current status:
+      const text = `Snapshot not READY before deadline (last status: ${lastStatus ?? "unknown"}). Current status:
 
 ${statusText}`;
-        return { content: [{ type: "text", text }] };
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server.registerTool(
+    "dump_bush",
+    {
+      title: "Dump Raw Index (Debug)",
+      description: "Debug tool. Downloads the raw HDF5 bush file for the current snapshot and saves it to the specified path. Returns an HDF5 bush reader skill with format documentation and Python code examples.",
+      inputSchema: {
+        filePath: z.string().min(1, "File path is required").refine((p) => p.endsWith(".h5"), "File must have .h5 extension").describe(
+          "Full file name to save (use base dir + any name with .h5 extension), e.g. /tmp/snapshot.h5"
+        )
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
       }
-      const effectiveBudget = Math.max(100, budgetTokens ?? 1e4);
-      try {
-        const result = await runtime.clients.retrieval.query(
-          readyHash,
-          query,
-          effectiveBudget,
-          { formatter: runtime.config.retrievalFormatter }
+    },
+    async ({ filePath }) => {
+      const deadline = Date.now() + runtime.config.maxQueryWaitMs;
+      while (Date.now() < deadline) {
+        if (isLocalStable()) break;
+        await sleep3(250);
+      }
+      if (!isLocalStable()) {
+        const statusText2 = formatStatus(
+          await collectIndexingStatus(runtime, runner)
         );
         return {
           content: [
             {
               type: "text",
-              text: result.formatted_output ?? "(no formatted output)"
+              text: `Indexer not ready (local hashing/dirty). Current status:
+
+${statusText2}`
             }
-          ]
-        };
-      } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown retrieval error";
-        runtime.logger.error({ err: error }, "Retrieval query failed");
-        return {
-          content: [{ type: "text", text: `Retrieval error: ${message}` }],
+          ],
           isError: true
         };
       }
+      let currentHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+      let lastStatus;
+      while (Date.now() < deadline) {
+        if (!isLocalStable()) {
+          while (Date.now() < deadline) {
+            if (isLocalStable()) break;
+            await sleep3(250);
+          }
+          if (!isLocalStable()) break;
+          currentHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+          continue;
+        }
+        try {
+          const status = await withDeadline2(
+            runtime.clients.sync.checkSnapshotStatus(currentHash),
+            deadline
+          );
+          lastStatus = status.status;
+          if (status.status === "READY") {
+            const bushBuffer = await withDeadline2(
+              runtime.clients.sync.downloadSnapshotBush(currentHash),
+              deadline
+            );
+            await mkdir(dirname(filePath), { recursive: true });
+            await writeFile(filePath, Buffer.from(bushBuffer));
+            runtime.logger.info(
+              {
+                filePath,
+                snapshotHash: currentHash,
+                bytes: bushBuffer.byteLength
+              },
+              "HDF5 bush file saved"
+            );
+            const skill = await withDeadline2(
+              runtime.clients.sync.getHdf5BushReaderSkill(),
+              deadline
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `HDF5 bush saved to ${filePath} (${bushBuffer.byteLength} bytes, snapshot ${currentHash}).
+
+${skill}`
+                }
+              ]
+            };
+          }
+          if (status.status === "FAILED") {
+            while (Date.now() < deadline) {
+              if (isLocalStable()) break;
+              await sleep3(250);
+            }
+            if (!isLocalStable()) break;
+            currentHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+            continue;
+          }
+          runtime.outbox.enqueueSnapshot(runtime.config.rootId, 0);
+        } catch {
+        }
+        const newHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+        if (newHash !== currentHash) {
+          currentHash = newHash;
+          continue;
+        }
+        await sleep3(500);
+      }
+      const statusText = formatStatus(
+        await collectIndexingStatus(runtime, runner)
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Snapshot not READY before deadline (last status: ${lastStatus ?? "unknown"}). Current status:
+
+${statusText}`
+          }
+        ],
+        isError: true
+      };
     }
   );
   return server;