jules-orchestrator-kit 0.22.9 → 0.23.0

package/bin/agentctl.mjs

@@ -14,7 +14,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.22.9 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.23.0 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.22.9",
+  "version": "0.23.0",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",

package/src/dag-engine.mjs

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { readFileSync, existsSync } from "node:fs";
+import { appendTelemetry } from "./telemetry.mjs";
 
 /**
  * Custom error thrown when a circular dependency is detected in the DAG.
@@ -200,8 +201,17 @@ export class DagExecutor {
    * @param {Object} [options]
    * @param {number} [options.concurrency]
    * @param {number} [options.taskTimeout]
+   * @param {string} [options.root]
+   * @param {Object} [options.progressBus]
+   * @param {string} [options.progressToken]
    */
-  async execute({ concurrency = this.concurrency, taskTimeout = this.taskTimeout } = {}) {
+  async execute({
+    concurrency = this.concurrency,
+    taskTimeout = this.taskTimeout,
+    root,
+    progressBus,
+    progressToken,
+  } = {}) {
     this.isExecuting = true;
     const { dependents } = this.validateDag();
 
@@ -265,6 +275,7 @@ export class DagExecutor {
           }
 
           running.add(taskId);
+          if (root) appendTelemetry(root, "dag_task_started", { taskId });
 
           (async () => {
             try {
@@ -291,6 +302,17 @@ export class DagExecutor {
               running.delete(taskId);
               completed.add(taskId);
 
+              if (root) appendTelemetry(root, "dag_task_completed", { taskId });
+              if (progressBus && progressToken) {
+                const pct = Math.round((completed.size / this.tasks.size) * 100);
+                progressBus.reportProgress(
+                  progressToken,
+                  pct,
+                  100,
+                  `Task ${taskId} completed (${completed.size}/${this.tasks.size})`
+                );
+              }
+
               for (const depNode of dependents.get(taskId)) {
                 inDegree.set(depNode, inDegree.get(depNode) - 1);
               }

package/src/engine.mjs

@@ -8,6 +8,7 @@ import { recordVerifyRun, readVerifyRuns, flakyVerdict } from "./flaky-ledger.mj
 import { readdirSync, readFileSync, renameSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
+import { appendTelemetry } from "./telemetry.mjs";
 
 export { recordVerifyRun, readVerifyRuns, flakyVerdict, sanitizeUntrustedData };
 
@@ -100,8 +101,12 @@ export async function gate(opts = {}) {
   const root = opts.root || process.cwd();
   const config = opts.config || loadConfig(root);
   const base = opts.base || config.baseBranch || "main";
+  const progressBus = opts.progressBus;
+  const progressToken = opts.progressToken;
   const phases = [];
 
+  appendTelemetry(root, "gate_started", { base });
+
   let files = [];
   let bytes = 0;
   let diffStr = "";
@@ -112,6 +117,7 @@ export async function gate(opts = {}) {
     diffStr = diffText(root, base);
   } catch (err) {
     phases.push({ phase: "git_resolution", ok: false, error: err.message });
+    appendTelemetry(root, "gate_finished", { ok: false, code: 1, error: err.message });
     return { ok: false, code: 1, phases, error: err.message };
   }
 
@@ -142,7 +148,13 @@ export async function gate(opts = {}) {
   });
 
   phases.push({ phase: "scope", ok: scopeResult.ok, violations: scopeResult.violations });
+  appendTelemetry(root, "gate_phase", { phase: "scope", ok: scopeResult.ok });
+  if (progressBus && progressToken) {
+    progressBus.reportProgress(progressToken, 25, 100, "Phase 1/4: Scope Guard verification complete");
+  }
+
   if (!scopeResult.ok) {
+    appendTelemetry(root, "gate_finished", { ok: false, code: 3 });
     return { ok: false, code: 3, phases };
   }
 
@@ -150,14 +162,26 @@ export async function gate(opts = {}) {
   const limitBytes = (config.limits.diffKb || 75) * 1024;
   const payloadOk = bytes <= limitBytes;
   phases.push({ phase: "payload", ok: payloadOk, bytes, limitBytes });
+  appendTelemetry(root, "gate_phase", { phase: "payload", ok: payloadOk });
+  if (progressBus && progressToken) {
+    progressBus.reportProgress(progressToken, 50, 100, "Phase 2/4: Diff Payload Governor check complete");
+  }
+
   if (!payloadOk) {
+    appendTelemetry(root, "gate_finished", { ok: false, code: 5 });
     return { ok: false, code: 5, phases };
   }
 
   // Phase 3: Diff Secret Scanner
   const secretResult = scanDiff(diffStr);
   phases.push({ phase: "secrets", ok: secretResult.ok, findings: secretResult.findings });
+  appendTelemetry(root, "gate_phase", { phase: "secrets", ok: secretResult.ok });
+  if (progressBus && progressToken) {
+    progressBus.reportProgress(progressToken, 75, 100, "Phase 3/4: Diff Secret Scanner check complete");
+  }
+
   if (!secretResult.ok) {
+    appendTelemetry(root, "gate_finished", { ok: false, code: 6 });
     return { ok: false, code: 6, phases };
   }
 
@@ -195,6 +219,8 @@ export async function gate(opts = {}) {
       flakyVerdictResult = flakyVerdict(runs);
       if (flakyVerdictResult.verdict === "QUARANTINED") {
         phases.push({ phase: "verify", ok: false, testResult, buildResult, flakyVerdict: flakyVerdictResult });
+        appendTelemetry(root, "gate_phase", { phase: "verify", ok: false, quarantined: true });
+        appendTelemetry(root, "gate_finished", { ok: false, code: 8 });
         return { ok: false, code: 8, phases, flakyVerdict: flakyVerdictResult };
       }
     }
@@ -208,16 +234,25 @@ export async function gate(opts = {}) {
   const verifyOk = testResult.ok && buildResult.ok;
   const failingCmd = !testResult.ok ? testResult : !buildResult.ok ? buildResult : null;
   phases.push({ phase: "verify", ok: verifyOk, testResult, buildResult });
+  appendTelemetry(root, "gate_phase", { phase: "verify", ok: verifyOk });
+  if (progressBus && progressToken) {
+    progressBus.reportProgress(progressToken, 100, 100, "Phase 4/4: Automated Test & Build Verification complete");
+  }
 
   if (!verifyOk && opts.fix) {
-    const repairs = await repair(failingCmd, { config, root, signal: opts.signal });
+    const repairs = await repair(failingCmd, { config, root, signal: opts.signal, progressBus, progressToken });
+    const finalOk = repairs.ok;
+    const finalCode = repairs.ok ? 0 : 4;
+    appendTelemetry(root, "gate_finished", { ok: finalOk, code: finalCode, repaired: true });
     if (repairs.ok) {
       return { ok: true, code: 0, phases, repairs };
     }
     return { ok: false, code: 4, phases, repairs };
   }
 
-  return { ok: verifyOk, code: verifyOk ? 0 : 4, phases };
+  const code = verifyOk ? 0 : 4;
+  appendTelemetry(root, "gate_finished", { ok: verifyOk, code });
+  return { ok: verifyOk, code, phases };
 }
 
 /**
@@ -280,6 +315,8 @@ export async function repair(failure, opts = {}) {
   const config = opts.config || loadConfig(root);
   const maxRetries = config.limits.repairAttempts || 3;
   const provider = opts.provider || createProvider(config.provider, config);
+  const progressBus = opts.progressBus;
+  const progressToken = opts.progressToken;
   const attempts = [];
   const breaker = opts.circuitBreaker || new OODACircuitBreaker({
     windowSize: Math.max(maxRetries + 1, 6),
@@ -292,6 +329,10 @@ export async function repair(failure, opts = {}) {
   breaker.observe(initialFingerprint);
 
   for (let n = 1; n <= maxRetries; n++) {
+    if (progressBus && progressToken) {
+      progressBus.reportProgress(progressToken, Math.round((n / maxRetries) * 100), 100, `OODA Repair attempt ${n}/${maxRetries}`);
+    }
+
     const repairPrompt = buildRepairPrompt(currentFailure, n, config);
     let session;
     try {
@@ -306,13 +347,15 @@ export async function repair(failure, opts = {}) {
       );
     } catch (err) {
       attempts.push({ n, ok: false, error: err.message });
+      appendTelemetry(root, "ooda_repair_attempt", { attempt: n, ok: false, error: err.message });
       break;
     }
 
     attempts.push({ n, session, ok: true });
+    appendTelemetry(root, "ooda_repair_attempt", { attempt: n, ok: true });
 
     // Re-verify after repair attempt
-    const gateRes = await gate({ root, config, fix: false });
+    const gateRes = await gate({ root, config, fix: false, progressBus, progressToken });
     if (gateRes.ok) {
       breaker.reset();
       return { ok: true, attempts, finalStatus: "PASSED" };

package/src/mcp-progress.mjs

@@ -0,0 +1,158 @@
+import { writeMcpFrame } from "./mcp.mjs";
+
+export const MAX_PROGRESS_MESSAGE_LENGTH = 240;
+export const DEFAULT_PROGRESS_COALESCE_MS = 150;
+
+/**
+ * MCP Progress & Event Streaming Bus with 150ms window coalescing and backpressure safety.
+ */
+export class ProgressBus {
+  /**
+   * @param {import("node:stream").Writable} [output=process.stdout]
+   * @param {Object} [opts={}]
+   * @param {number} [opts.coalesceMs=150]
+   */
+  constructor(output = process.stdout, opts = {}) {
+    this.output = output || process.stdout;
+    this.coalesceMs = opts.coalesceMs ?? DEFAULT_PROGRESS_COALESCE_MS;
+    this.pending = new Map(); // token -> { timer, latestPayload }
+    this.queue = [];
+    this.isWriting = false;
+    this.isDraining = false;
+  }
+
+  /**
+   * Internal queue flusher with stream backpressure handling.
+   * @private
+   */
+  async _flushQueue() {
+    this.isWriting = true;
+    while (this.queue.length > 0) {
+      if (this.isDraining) {
+        await new Promise((resolve) => {
+          if (!this.output || typeof this.output.once !== "function") {
+            return resolve();
+          }
+          this.output.once("drain", resolve);
+        });
+        this.isDraining = false;
+      }
+
+      const frame = this.queue.shift();
+      const ok = writeMcpFrame(this.output, frame);
+      if (!ok) {
+        this.isDraining = true;
+      }
+    }
+    this.isWriting = false;
+  }
+
+  /**
+   * Sends a framed JSON-RPC payload to output via authorized writeMcpFrame.
+   * @param {Object} payload
+   */
+  async sendFrame(payload) {
+    const frameStr = JSON.stringify(payload) + "\n";
+    this.queue.push(frameStr);
+    if (!this.isWriting) {
+      await this._flushQueue();
+    }
+  }
+
+  /**
+   * Reports progress for an active progressToken.
+   * Coalesces rapid intermediate updates within a 150ms window (latest-wins).
+   *
+   * @param {string} progressToken
+   * @param {number} progress
+   * @param {number|null} [total=null]
+   * @param {string|null} [message=null]
+   */
+  reportProgress(progressToken, progress, total = null, message = null) {
+    if (!progressToken) return;
+
+    let cappedMessage = undefined;
+    if (message !== null && message !== undefined) {
+      const msgStr = String(message);
+      cappedMessage =
+        msgStr.length > MAX_PROGRESS_MESSAGE_LENGTH
+          ? msgStr.slice(0, MAX_PROGRESS_MESSAGE_LENGTH)
+          : msgStr;
+    }
+
+    const params = {
+      progressToken,
+      progress,
+    };
+    if (total !== null && total !== undefined) params.total = total;
+    if (cappedMessage !== undefined) params.message = cappedMessage;
+
+    const payload = {
+      jsonrpc: "2.0",
+      method: "notifications/progress",
+      params,
+    };
+
+    const isComplete = total !== null && total !== undefined && progress >= total;
+    const existing = this.pending.get(progressToken);
+
+    if (isComplete) {
+      if (existing?.timer) clearTimeout(existing.timer);
+      this.pending.delete(progressToken);
+      this.sendFrame(payload);
+      return;
+    }
+
+    if (!existing) {
+      // First update in window: send immediately
+      this.sendFrame(payload);
+      const timer = setTimeout(() => {
+        const current = this.pending.get(progressToken);
+        if (current?.latestPayload) {
+          this.sendFrame(current.latestPayload);
+        }
+        this.pending.delete(progressToken);
+      }, this.coalesceMs);
+
+      this.pending.set(progressToken, { timer, latestPayload: null });
+    } else {
+      // Intermediate update: save latest payload
+      existing.latestPayload = payload;
+    }
+  }
+
+  /**
+   * Emits an MCP log notification frame (notifications/message).
+   * Never calls raw console.log.
+   *
+   * @param {string} [level="info"] "info" | "warning" | "error" | "debug"
+   * @param {string|Object} [data=""]
+   * @param {string} [logger="jules-orchestrator"]
+   */
+  log(level = "info", data = "", logger = "jules-orchestrator") {
+    const payload = {
+      jsonrpc: "2.0",
+      method: "notifications/message",
+      params: {
+        level,
+        logger,
+        data: typeof data === "string" ? data : JSON.stringify(data),
+      },
+    };
+    return this.sendFrame(payload);
+  }
+
+  /**
+   * Flushes all pending progress timers and ensures output queue is completely drained.
+   */
+  async flush() {
+    for (const [token, item] of this.pending.entries()) {
+      if (item.timer) clearTimeout(item.timer);
+      if (item.latestPayload) {
+        this.sendFrame(item.latestPayload);
+      }
+      this.pending.delete(token);
+    }
+    await this._flushQueue();
+  }
+}

package/src/mcp.mjs

@@ -4,10 +4,12 @@ import { gate, dispatch } from "./engine.mjs";
 import { classifyRiskTier } from "./risk.mjs";
 import { checkDailyBudget, lockStatus } from "./state.mjs";
 import { reapOrphanedIntents, reapStaleMutexDirs } from "./journal.mjs";
+import { readTelemetry } from "./telemetry.mjs";
+import { ProgressBus } from "./mcp-progress.mjs";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
-  version: "0.22.9",
+  version: "0.23.0",
 };
 
 export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling
@@ -136,6 +138,16 @@ export const MCP_TOOLS = [
       properties: {},
     },
   },
+  {
+    name: "telemetry_tail",
+    description: "Query the last N telemetry events from the orchestrator telemetry spine.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Number of telemetry events to retrieve (default 50, max 500)" },
+      },
+    },
+  },
 ];
 
 export async function handleMcpRequest(request, opts = {}) {
@@ -260,6 +272,25 @@ export async function handleMcpRequest(request, opts = {}) {
         };
       }
 
+      if (toolName === "telemetry_tail") {
+        if (args.limit !== undefined && (typeof args.limit !== "number" || args.limit < 1)) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Invalid parameters: 'limit' must be a positive number" },
+          };
+        }
+        const limit = Math.min(args.limit || 50, 500);
+        const events = readTelemetry(root, limit);
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(events, null, 2) }],
+          },
+        };
+      }
+
       return {
         jsonrpc: "2.0",
         id,
@@ -361,11 +392,14 @@ export function startMcpServer(input = process.stdin, output = process.stdout, o
     isolateMcpStdout(output, opts);
   }
 
+  const progressBus = opts.progressBus || new ProgressBus(output, opts);
   const decoder = new McpFrameDecoder({ maxFrameSize: opts.maxFrameSize || MAX_MCP_FRAME_SIZE });
 
   decoder.on("data", async (request) => {
     try {
-      const response = await handleMcpRequest(request, opts);
+      const progressToken = request?.params?._meta?.progressToken || request?.params?.progressToken;
+      const requestOpts = { ...opts, progressBus, progressToken };
+      const response = await handleMcpRequest(request, requestOpts);
       if (response !== null && response !== undefined) {
         writeMcpFrame(output, JSON.stringify(response) + "\n");
       }

package/src/security.mjs

@@ -64,7 +64,9 @@ export function safeAtomicWrite(filePath, content, options = {}) {
   const fd = openSync(tempFile, "wx", mode);
   try {
     writeSync(fd, content, null, encoding);
-    fsyncSync(fd);
+    if (options.sync !== false) {
+      fsyncSync(fd);
+    }
   } finally {
     closeSync(fd);
   }

package/src/telemetry.mjs

@@ -0,0 +1,275 @@
+import {
+  openSync,
+  writeSync,
+  closeSync,
+  readFileSync,
+  existsSync,
+  statSync,
+  readdirSync,
+} from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { resolveRoot } from "./config.mjs";
+import { getStateDir, withVfsMutex } from "./state.mjs";
+import { safeAtomicWrite } from "./security.mjs";
+
+export const MAX_TELEMETRY_SEGMENT_BYTES = 8 * 1024 * 1024; // 8 MB log segment ceiling
+export const TELEMETRY_GENESIS_HASH = "0".repeat(64);
+
+/**
+ * Returns telemetry file paths for a given date string sorted by segment index.
+ */
+function getTelemetrySegmentFiles(stateDir, dateStr) {
+  if (!existsSync(stateDir)) return [];
+  const prefix = `telemetry-${dateStr}`;
+  const files = readdirSync(stateDir).filter(
+    (f) => f.startsWith(prefix) && f.endsWith(".jsonl")
+  );
+
+  return files
+    .map((name) => {
+      let index = 0;
+      if (name !== `${prefix}.jsonl`) {
+        const match = name.match(/telemetry-[0-9]{4}-[0-9]{2}-[0-9]{2}-([0-9]+)\.jsonl$/);
+        if (match) index = parseInt(match[1], 10);
+      }
+      return { name, path: join(stateDir, name), index };
+    })
+    .sort((a, b) => a.index - b.index);
+}
+
+/**
+ * Performs a cold scan of telemetry jsonl files to recover the last valid hash and active segment index.
+ */
+function coldScanTelemetry(stateDir, dateStr) {
+  const segments = getTelemetrySegmentFiles(stateDir, dateStr);
+  if (segments.length === 0) {
+    return { hash: TELEMETRY_GENESIS_HASH, segment: 0 };
+  }
+
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const seg = segments[i];
+    if (existsSync(seg.path)) {
+      try {
+        const content = readFileSync(seg.path, "utf-8");
+        const lines = content.split("\n").filter(Boolean);
+        for (let j = lines.length - 1; j >= 0; j--) {
+          try {
+            const entry = JSON.parse(lines[j]);
+            if (entry && typeof entry.hash === "string") {
+              return { hash: entry.hash, segment: seg.index };
+            }
+          } catch (_) {}
+        }
+      } catch (_) {}
+    }
+  }
+
+  return { hash: TELEMETRY_GENESIS_HASH, segment: 0 };
+}
+
+/**
+ * Appends a structured telemetry event to .agent/state/telemetry-<date>.jsonl with SHA-256 hash chaining.
+ * Uses .head atomic cache for O(1) constant-time appends.
+ *
+ * @param {string} [rootOrOpts]
+ * @param {string} kind
+ * @param {Object} [fields={}]
+ * @returns {Object} Appended telemetry record
+ */
+export function appendTelemetry(rootOrOpts = resolveRoot(), kind = "event", fields = {}) {
+  const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
+  const stateDir = getStateDir(root);
+  const mutexDir = join(stateDir, ".telemetry.mutex");
+
+  return withVfsMutex(mutexDir, () => {
+    const dateStr = new Date().toISOString().split("T")[0];
+    const headPath = join(stateDir, `telemetry-${dateStr}.head`);
+
+    let prevHash = TELEMETRY_GENESIS_HASH;
+    let activeSegmentIndex = 0;
+    let headValid = false;
+
+    if (existsSync(headPath)) {
+      try {
+        const headContent = readFileSync(headPath, "utf-8");
+        const headObj = JSON.parse(headContent);
+        if (headObj && typeof headObj.hash === "string") {
+          prevHash = headObj.hash;
+          activeSegmentIndex = typeof headObj.segment === "number" ? headObj.segment : 0;
+          headValid = true;
+        }
+      } catch (_) {}
+    }
+
+    if (!headValid) {
+      const recovered = coldScanTelemetry(stateDir, dateStr);
+      prevHash = recovered.hash;
+      activeSegmentIndex = recovered.segment;
+    }
+
+    let activeFileName =
+      activeSegmentIndex === 0
+        ? `telemetry-${dateStr}.jsonl`
+        : `telemetry-${dateStr}-${activeSegmentIndex}.jsonl`;
+    let activeFilePath = join(stateDir, activeFileName);
+
+    if (existsSync(activeFilePath)) {
+      try {
+        const stat = statSync(activeFilePath);
+        if (stat.size >= MAX_TELEMETRY_SEGMENT_BYTES) {
+          activeSegmentIndex += 1;
+          activeFileName = `telemetry-${dateStr}-${activeSegmentIndex}.jsonl`;
+          activeFilePath = join(stateDir, activeFileName);
+        }
+      } catch (_) {}
+    }
+
+    const ts = new Date().toISOString();
+    const payloadWithoutHash = { v: 1, ts, kind, ...fields, prevHash };
+    const hash = createHash("sha256").update(JSON.stringify(payloadWithoutHash)).digest("hex");
+    const entry = { ...payloadWithoutHash, hash };
+
+    const fd = openSync(activeFilePath, "a");
+    try {
+      writeSync(fd, JSON.stringify(entry) + "\n", "utf-8");
+    } finally {
+      closeSync(fd);
+    }
+
+    safeAtomicWrite(
+      headPath,
+      JSON.stringify({ v: 1, hash, segment: activeSegmentIndex, ts }),
+      { sync: false }
+    );
+
+    return entry;
+  });
+}
+
+/**
+ * Reads telemetry records across segments for a target date (or current date if omitted).
+ * Returns array of telemetry objects in chronological order.
+ *
+ * @param {string} [rootOrOpts]
+ * @param {number} [limit=50]
+ * @param {string} [targetDateStr]
+ * @returns {Array<Object>}
+ */
+export function readTelemetry(rootOrOpts = resolveRoot(), limit = 50, targetDateStr = null) {
+  const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
+  const stateDir = getStateDir(root);
+  const dateStr = targetDateStr || new Date().toISOString().split("T")[0];
+
+  const segments = getTelemetrySegmentFiles(stateDir, dateStr);
+  if (segments.length === 0) return [];
+
+  const allEntries = [];
+  for (const seg of segments) {
+    if (existsSync(seg.path)) {
+      try {
+        const raw = readFileSync(seg.path, "utf-8");
+        const lines = raw.split("\n").filter(Boolean);
+        for (const line of lines) {
+          try {
+            const entry = JSON.parse(line);
+            allEntries.push(Object.freeze(entry));
+          } catch (_) {}
+        }
+      } catch (_) {}
+    }
+  }
+
+  if (allEntries.length <= limit) {
+    return allEntries;
+  }
+  return allEntries.slice(allEntries.length - limit);
+}
+
+/**
+ * Verifies the cryptographic SHA-256 hash-chain integrity of telemetry records for a date.
+ *
+ * @param {string} [rootOrOpts]
+ * @param {string} [targetDateStr]
+ * @returns {Object}
+ */
+export function verifyTelemetryIntegrity(rootOrOpts = resolveRoot(), targetDateStr = null) {
+  const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
+  const stateDir = getStateDir(root);
+  const dateStr = targetDateStr || new Date().toISOString().split("T")[0];
+
+  const segments = getTelemetrySegmentFiles(stateDir, dateStr);
+  if (segments.length === 0) {
+    return { ok: true, count: 0, lastHash: TELEMETRY_GENESIS_HASH };
+  }
+
+  let expectedPrevHash = TELEMETRY_GENESIS_HASH;
+  let totalCount = 0;
+
+  for (const seg of segments) {
+    if (!existsSync(seg.path)) continue;
+    try {
+      const raw = readFileSync(seg.path, "utf-8");
+      const lines = raw.split("\n").filter(Boolean);
+      for (let i = 0; i < lines.length; i++) {
+        totalCount++;
+        let obj;
+        try {
+          obj = JSON.parse(lines[i]);
+        } catch (err) {
+          return { ok: false, segment: seg.name, line: i + 1, error: "TORN_WRITE_CORRUPTION", detail: err.message };
+        }
+
+        if (!obj.hash || !obj.prevHash) {
+          return { ok: false, segment: seg.name, line: i + 1, error: "MISSING_HASH_FIELDS" };
+        }
+
+        if (obj.prevHash !== expectedPrevHash) {
+          return {
+            ok: false,
+            segment: seg.name,
+            line: i + 1,
+            error: "BROKEN_PREV_HASH",
+            expected: expectedPrevHash,
+            actual: obj.prevHash,
+          };
+        }
+
+        const { hash, ...rest } = obj;
+        const recomputed = createHash("sha256").update(JSON.stringify(rest)).digest("hex");
+        if (recomputed !== hash) {
+          return {
+            ok: false,
+            segment: seg.name,
+            line: i + 1,
+            error: "CORRUPTED_ENTRY_HASH",
+            expected: recomputed,
+            actual: hash,
+          };
+        }
+        expectedPrevHash = hash;
+      }
+    } catch (err) {
+      return { ok: false, count: totalCount, error: err.message };
+    }
+  }
+
+  const headPath = join(stateDir, `telemetry-${dateStr}.head`);
+  if (existsSync(headPath)) {
+    try {
+      const headObj = JSON.parse(readFileSync(headPath, "utf-8"));
+      if (headObj.hash !== expectedPrevHash) {
+        return {
+          ok: false,
+          error: "HEAD_HASH_MISMATCH",
+          expected: expectedPrevHash,
+          actual: headObj.hash,
+        };
+      }
+    } catch (_) {
+      return { ok: false, error: "CORRUPTED_HEAD_FILE" };
+    }
+  }
+
+  return { ok: true, count: totalCount, lastHash: expectedPrevHash };
+}