jules-orchestrator-kit 0.22.8 → 0.23.0

package/bin/agentctl.mjs

@@ -14,7 +14,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.22.8 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.23.0 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -44,7 +44,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.22.8");
+    console.log("agentctl v0.22.9");
     process.exit(0);
   }
 
@@ -226,7 +226,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.22.8)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v0.22.9)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.22.8",
+  "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.
@@ -14,23 +15,50 @@ export class DagCycleError extends Error {
 }
 
 /**
- * Zero-Dependency Task DAG Executor with cycle detection and interface fingerprinting.
+ * Wraps an async runner function with a timeout (default 15 minutes = 900,000 ms).
+ * @param {Function} runner
+ * @param {number} [timeoutMs=900000]
+ * @returns {Promise<any>}
+ */
+export async function withTaskTimeout(runner, timeoutMs = 15 * 60 * 1000) {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`Task execution timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([runner(), timeoutPromise]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Zero-Dependency Task DAG Executor with cycle detection, interface fingerprinting, and execution freezing.
  */
 export class DagExecutor {
-  constructor({ concurrency = 4 } = {}) {
+  constructor({ concurrency = 4, taskTimeout = 15 * 60 * 1000 } = {}) {
     this.concurrency = concurrency;
+    this.taskTimeout = taskTimeout;
     this.tasks = new Map();
+    this.isExecuting = false;
   }
 
   /**
-   * Registers a task into the DAG.
+   * Registers a task into the DAG. Throws if called after execution has started.
    * @param {Object} task
    * @param {string} task.id
    * @param {string[]} [task.dependsOn=[]]
    * @param {string[]} [task.outputs=[]]
    * @param {Function} [task.runner]
+   * @param {number} [task.timeout]
    */
-  addTask({ id, dependsOn = [], outputs = [], runner }) {
+  addTask({ id, dependsOn = [], outputs = [], runner, timeout }) {
+    if (this.isExecuting) {
+      throw new Error("Cannot add task after execution has started");
+    }
     if (!id || typeof id !== "string") {
       throw new Error("Task id must be a non-empty string");
     }
@@ -42,6 +70,7 @@ export class DagExecutor {
       dependsOn: Array.isArray(dependsOn) ? [...dependsOn] : [],
       outputs: Array.isArray(outputs) ? [...outputs] : [],
       runner: runner || (async () => {}),
+      timeout,
     });
   }
 
@@ -171,8 +200,19 @@ export class DagExecutor {
    * Executes tasks in topological order with parallel concurrency and interface fingerprinting.
    * @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 } = {}) {
+  async execute({
+    concurrency = this.concurrency,
+    taskTimeout = this.taskTimeout,
+    root,
+    progressBus,
+    progressToken,
+  } = {}) {
+    this.isExecuting = true;
     const { dependents } = this.validateDag();
 
     const completed = new Set();
@@ -221,7 +261,7 @@ export class DagExecutor {
             for (const depId of task.dependsOn) {
               const depTask = this.tasks.get(depId);
               for (const outputFile of depTask.outputs) {
-                const expectedHash = fingerprints.get(outputFile);
+                const expectedHash = fingerprints.get(`${depId}:${outputFile}`) ?? fingerprints.get(outputFile);
                 const actualHash = this._computeFileHash(outputFile);
                 if (expectedHash !== actualHash) {
                   throw new Error(
@@ -235,26 +275,44 @@ export class DagExecutor {
           }
 
           running.add(taskId);
+          if (root) appendTelemetry(root, "dag_task_started", { taskId });
 
           (async () => {
             try {
               executionHistory.push(taskId);
-              await task.runner({
-                id: task.id,
-                dependsOn: task.dependsOn,
-                outputs: task.outputs,
-                fingerprints,
-              });
-
-              // Post-task Interface Fingerprinting
+              const timeoutMs = task.timeout || taskTimeout;
+              await withTaskTimeout(
+                () =>
+                  task.runner({
+                    id: task.id,
+                    dependsOn: task.dependsOn,
+                    outputs: task.outputs,
+                    fingerprints,
+                  }),
+                timeoutMs
+              );
+
+              // Post-task Interface Fingerprinting (keyed by taskId:filePath and filePath alias)
               for (const outputFile of task.outputs) {
                 const hash = this._computeFileHash(outputFile);
+                fingerprints.set(`${taskId}:${outputFile}`, hash);
                 fingerprints.set(outputFile, hash);
               }
 
               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,8 +8,9 @@ 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 };
+export { recordVerifyRun, readVerifyRuns, flakyVerdict, sanitizeUntrustedData };
 
 /**
  * Validates whether a file in .agent/jules-queue/ is a task file.
@@ -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.8",
+  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/merge-blocks.mjs

@@ -0,0 +1,238 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Computes SHA-1 hash of a string.
+ * @param {string} content
+ * @returns {string} SHA-1 hex string
+ */
+function sha1(content) {
+  return createHash("sha1").update(content).digest("hex");
+}
+
+/**
+ * Chunks source code text into declaration blocks bounded by column-0 declaration boundaries.
+ * @param {string} text
+ * @param {string} [lang="js"]
+ * @returns {Array<Object>} Array of block descriptors
+ */
+export function chunkBlocks(text = "", lang = "js") {
+  if (typeof text !== "string") {
+    text = String(text || "");
+  }
+
+  const lines = text.split(/\r?\n/);
+  const blocks = [];
+  const nameCounts = new Map();
+
+  const isPython = lang === "py" || lang === "python";
+
+  // Declaration regex matching column 0
+  const declRegex = /^(?:export\s+)?(?:async\s+)?(function\*?|class|const|let|var|def|type|interface|enum)\s+([a-zA-Z0-9_$]+)/;
+  const declAnyRegex = /^(?:export\s+)?(?:async\s+)?(function\*?|class|const|let|var|def|type|interface|enum)\b/;
+
+  let currentLines = [];
+  let currentType = "prelude";
+  let currentName = null;
+  let inBlock = false;
+  let braceDepth = 0;
+  let blockIndentLevel = 0;
+
+  function flushBlock() {
+    if (currentLines.length === 0) return;
+    const content = currentLines.join("\n");
+    if (currentType === "prelude" && content.trim().length === 0) {
+      currentLines = [];
+      return;
+    }
+    let name = currentName;
+    if (!name) {
+      name = currentType === "prelude" ? `prelude_${blocks.length}` : `block_${blocks.length}`;
+    }
+
+    // Ensure unique block ID if duplicate names exist
+    const count = (nameCounts.get(name) || 0) + 1;
+    nameCounts.set(name, count);
+    const uniqueId = count > 1 ? `${currentType}:${name}:${count}` : `${currentType}:${name}`;
+
+    blocks.push({
+      id: uniqueId,
+      name,
+      type: currentType,
+      lines: [...currentLines],
+      content,
+      hash: sha1(content),
+      indentation: blockIndentLevel,
+    });
+
+    currentLines = [];
+    currentType = "prelude";
+    currentName = null;
+    inBlock = false;
+    braceDepth = 0;
+    blockIndentLevel = 0;
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const isColumnZero = line.length > 0 && line[0] !== " " && line[0] !== "\t";
+
+    if (isPython) {
+      // Python block logic
+      if (isColumnZero && declAnyRegex.test(line)) {
+        flushBlock();
+        const match = line.match(declRegex);
+        currentType = match ? match[1] : "def";
+        currentName = match ? match[2] : null;
+        inBlock = true;
+        blockIndentLevel = 0;
+      } else if (inBlock && isColumnZero && line.trim().length > 0 && !line.trim().startsWith("#")) {
+        // Dedented back to column 0 in Python
+        flushBlock();
+      }
+    } else {
+      // JS/TS block logic
+      if (isColumnZero && declAnyRegex.test(line)) {
+        flushBlock();
+        const match = line.match(declRegex);
+        currentType = match ? match[1] : "decl";
+        currentName = match ? match[2] : null;
+        inBlock = true;
+        blockIndentLevel = 0;
+      }
+    }
+
+    currentLines.push(line);
+
+    if (!isPython && inBlock) {
+      // Track curly brace balance for JS/TS
+      for (const char of line) {
+        if (char === "{") braceDepth++;
+        if (char === "}") braceDepth--;
+      }
+
+      // Check if block ends on this line
+      const isClosingBraceAtColZero = isColumnZero && line.trim() === "}";
+      const isSingleLineStatement = braceDepth <= 0 && (line.trim().endsWith(";") || isClosingBraceAtColZero);
+
+      if (braceDepth <= 0 && isSingleLineStatement) {
+        flushBlock();
+      }
+    }
+  }
+
+  flushBlock();
+  return blocks;
+}
+
+/**
+ * Performs a 3-way block structural merge between base, ours, and theirs.
+ * @param {string} baseText
+ * @param {string} oursText
+ * @param {string} theirsText
+ * @param {string} [lang="js"]
+ * @returns {Object} { mergedText, classifications, conflicts, toString() }
+ */
+export function mergeBlocks3Way(baseText = "", oursText = "", theirsText = "", lang = "js") {
+  const baseBlocks = chunkBlocks(baseText, lang);
+  const oursBlocks = chunkBlocks(oursText, lang);
+  const theirsBlocks = chunkBlocks(theirsText, lang);
+
+  const baseMap = new Map(baseBlocks.map((b) => [b.id, b]));
+  const theirsMap = new Map(theirsBlocks.map((b) => [b.id, b]));
+
+  const classifications = [];
+  const processed = new Set();
+  const outputBlocks = [];
+  let conflicts = 0;
+
+  // Process oursBlocks first
+  for (const oBlock of oursBlocks) {
+    const id = oBlock.id;
+    processed.add(id);
+
+    const bBlock = baseMap.get(id);
+    const tBlock = theirsMap.get(id);
+
+    if (tBlock && bBlock) {
+      if (oBlock.hash === tBlock.hash) {
+        // Both match exactly
+        classifications.push({ id, type: "IDENTICAL" });
+        outputBlocks.push(oBlock.content);
+      } else if (oBlock.hash === bBlock.hash) {
+        // Ours didn't change, theirs changed
+        classifications.push({ id, type: "ONLY_THEIRS" });
+        outputBlocks.push(tBlock.content);
+      } else if (tBlock.hash === bBlock.hash) {
+        // Theirs didn't change, ours changed
+        classifications.push({ id, type: "ONLY_OURS" });
+        outputBlocks.push(oBlock.content);
+      } else {
+        // Both changed differently
+        conflicts++;
+        classifications.push({ id, type: "CONFLICT_EDIT_EDIT" });
+        outputBlocks.push(`<<<<<<< OURS\n${oBlock.content}\n=======\n${tBlock.content}\n>>>>>>> THEIRS`);
+      }
+    } else if (tBlock && !bBlock) {
+      // Added in both ours and theirs
+      if (oBlock.hash === tBlock.hash) {
+        classifications.push({ id, type: "IDENTICAL" });
+        outputBlocks.push(oBlock.content);
+      } else {
+        conflicts++;
+        classifications.push({ id, type: "CONFLICT_EDIT_EDIT" });
+        outputBlocks.push(`<<<<<<< OURS\n${oBlock.content}\n=======\n${tBlock.content}\n>>>>>>> THEIRS`);
+      }
+    } else if (!tBlock && bBlock) {
+      // Present in base and ours, missing in theirs
+      if (oBlock.hash === bBlock.hash) {
+        // Deleted by theirs, unchanged by ours
+        classifications.push({ id, type: "DELETED" });
+      } else {
+        // Modified by ours, deleted by theirs -> CONFLICT
+        conflicts++;
+        classifications.push({ id, type: "CONFLICT_EDIT_EDIT" });
+        outputBlocks.push(`<<<<<<< OURS\n${oBlock.content}\n=======\n>>>>>>> THEIRS`);
+      }
+    } else {
+      // !tBlock && !bBlock -> ADDED_OURS
+      classifications.push({ id, type: "ADDED_OURS" });
+      outputBlocks.push(oBlock.content);
+    }
+  }
+
+  // Handle blocks in theirs that were not in ours
+  for (const tBlock of theirsBlocks) {
+    const id = tBlock.id;
+    if (processed.has(id)) continue;
+    processed.add(id);
+
+    const bBlock = baseMap.get(id);
+    if (!bBlock) {
+      // Added in theirs
+      classifications.push({ id, type: "ADDED_THEIRS" });
+      outputBlocks.push(tBlock.content);
+    } else {
+      // Present in base and theirs, deleted by ours
+      if (tBlock.hash === bBlock.hash) {
+        // Deleted by ours, unchanged by theirs
+        classifications.push({ id, type: "DELETED" });
+      } else {
+        // Modified by theirs, deleted by ours -> CONFLICT
+        conflicts++;
+        classifications.push({ id, type: "CONFLICT_EDIT_EDIT" });
+        outputBlocks.push(`<<<<<<< OURS\n=======\n${tBlock.content}\n>>>>>>> THEIRS`);
+      }
+    }
+  }
+
+  const mergedText = outputBlocks.join("\n\n");
+
+  return {
+    mergedText,
+    classifications,
+    conflicts,
+    toString() {
+      return this.mergedText;
+    },
+  };
+}

package/src/merge-verify.mjs

@@ -0,0 +1,63 @@
+import { writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { join, basename, extname } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+/**
+ * Syntax Verification Chain validating merged output via target runtime tools.
+ * @param {string} mergedText
+ * @param {string} fileName
+ * @param {string} [root=process.cwd()]
+ * @returns {{ ok: boolean, tool: string, error?: string }}
+ */
+export function mergeVerifyChain(mergedText, fileName, root = process.cwd()) {
+  const ext = extname(fileName).toLowerCase();
+  const base = basename(fileName) || `temp_file${ext}`;
+  const tempDir = join(tmpdir(), `merge-verify-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  
+  mkdirSync(tempDir, { recursive: true });
+  const tempFilePath = join(tempDir, base);
+
+  try {
+    writeFileSync(tempFilePath, mergedText, "utf8");
+
+    let cmd = "";
+    let args = [];
+    let tool = "";
+
+    if (ext === ".py") {
+      cmd = "python3";
+      args = ["-m", "py_compile", tempFilePath];
+      tool = "python3 -m py_compile";
+    } else if (ext === ".ts" || ext === ".tsx" || ext === ".mts" || ext === ".cts") {
+      const hasTsConfig = existsSync(join(root, "tsconfig.json"));
+      if (hasTsConfig) {
+        cmd = "npx";
+        args = ["tsc", "--noEmit", tempFilePath];
+        tool = "tsc --noEmit";
+      } else {
+        cmd = "node";
+        args = ["--check", tempFilePath];
+        tool = "node --check";
+      }
+    } else {
+      // JS, MJS, CJS or default
+      cmd = "node";
+      args = ["--check", tempFilePath];
+      tool = "node --check";
+    }
+
+    const res = spawnSync(cmd, args, { encoding: "utf8" });
+    const ok = res.status === 0;
+
+    return {
+      ok,
+      tool,
+      ...(ok ? {} : { error: res.stderr || res.stdout || `Process exited with code ${res.status}` }),
+    };
+  } finally {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+}

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 };
+}