jules-orchestrator-kit 0.23.0 → 0.25.0

package/src/engine.mjs

@@ -1,8 +1,8 @@
 import { loadConfig, parseYaml, normalizeScope } from "./config.mjs";
 import { checkScope, scanDiff, redactSecrets } from "./security.mjs";
 import { changedFiles, diffBytes, diffText, showFromOrigin, runCmd } from "./git.mjs";
-import { createProvider } from "./provider.mjs";
-import { withBudget, appendLedger, getQueueDir, ensureDir } from "./state.mjs";
+import { createProvider, ProviderRateLimitError, ProviderUnavailableError } from "./provider.mjs";
+import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReservation } from "./state.mjs";
 import { sanitizeUntrustedData, buildAgentEnvelope } from "./prompt-guard.mjs";
 import { recordVerifyRun, readVerifyRuns, flakyVerdict } from "./flaky-ledger.mjs";
 import { readdirSync, readFileSync, renameSync, existsSync } from "node:fs";
@@ -346,6 +346,24 @@ export async function repair(failure, opts = {}) {
         config.limits.dailyTasks
       );
     } catch (err) {
+      if (err instanceof ProviderRateLimitError || err instanceof ProviderUnavailableError) {
+        if (err.reservationId) {
+          rollbackBudgetReservation(root, err.reservationId);
+        }
+        const retryAfterMs = err.retryAfterMs || 60000;
+        const backoffSec = Math.ceil(retryAfterMs / 1000);
+        console.warn(`[PROVIDER_INFRASTRUCTURE_FAILURE] ${err.name}: ${err.message}. Recommended backoff: ${backoffSec}s.`);
+        attempts.push({ n, ok: false, error: err.message, providerError: true, retryAfterMs });
+        appendTelemetry(root, "ooda_repair_attempt", { attempt: n, ok: false, error: err.message, providerError: true });
+        return {
+          ok: false,
+          attempts,
+          finalStatus: "PROVIDER_INFRASTRUCTURE_FAILURE",
+          error: err.message,
+          retryAfterMs,
+          providerError: true,
+        };
+      }
       attempts.push({ n, ok: false, error: err.message });
       appendTelemetry(root, "ooda_repair_attempt", { attempt: n, ok: false, error: err.message });
       break;
@@ -354,6 +372,16 @@ export async function repair(failure, opts = {}) {
     attempts.push({ n, session, ok: true });
     appendTelemetry(root, "ooda_repair_attempt", { attempt: n, ok: true });
 
+    // Poll async provider for terminal session state before executing re-verification gates
+    if (provider && session) {
+      await pollSessionState(provider, session, {
+        root,
+        dryRun: opts.dryRun,
+        pollIntervalMs: opts.pollIntervalMs,
+        maxPollAttempts: opts.maxPollAttempts,
+      });
+    }
+
     // Re-verify after repair attempt
     const gateRes = await gate({ root, config, fix: false, progressBus, progressToken });
     if (gateRes.ok) {
@@ -379,6 +407,50 @@ export async function repair(failure, opts = {}) {
   return { ok: false, attempts, finalStatus: "OODA_EXHAUSTED" };
 }
 
+/**
+ * Polls an async provider for terminal session state (COMPLETED / FAILED) before re-verification.
+ */
+export async function pollSessionState(provider, session, opts = {}) {
+  if (!session || !session.id) return { status: "COMPLETED" };
+  const initialStatus = String(session.status || session.state || "").toUpperCase();
+  if (initialStatus === "COMPLETED" || initialStatus === "FAILED" || opts.dryRun || session.id === "dry-run-session-id") {
+    return { status: initialStatus || "COMPLETED" };
+  }
+
+  const maxAttempts = opts.maxPollAttempts || 30;
+  const pollIntervalMs = opts.pollIntervalMs || 1000;
+  const timeoutMs = opts.pollTimeoutMs || 300000;
+  const startTime = Date.now();
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (Date.now() - startTime > timeoutMs) break;
+
+    let currentSession = null;
+    if (provider && typeof provider.getSession === "function") {
+      try {
+        currentSession = await provider.getSession(session.id, opts);
+      } catch (_) {}
+    } else if (typeof opts.pollFn === "function") {
+      try {
+        currentSession = await opts.pollFn(session.id);
+      } catch (_) {}
+    }
+
+    if (currentSession) {
+      const status = String(currentSession.status || currentSession.state || "").toUpperCase();
+      if (status === "COMPLETED" || status === "FAILED") {
+        return { ...currentSession, status };
+      }
+    } else {
+      break;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+
+  return { ...session, status: String(session.status || "COMPLETED").toUpperCase() };
+}
+
 function buildRepairPrompt(failure, attempt, _config) {
   const cleanStderr = redactSecrets(failure.stderr || failure.stdout || "Unknown Error");
 
@@ -428,39 +500,81 @@ export async function dispatch(task, opts = {}) {
 
   const cleanTask = { ...task, prompt: envelopedPrompt };
 
-  return withBudget(
-    () => provider.dispatch(cleanTask, { root, dryRun: opts.dryRun }),
-    root,
-    config.limits.dailyTasks
-  );
+  try {
+    return await withBudget(
+      () => provider.dispatch(cleanTask, { root, dryRun: opts.dryRun }),
+      root,
+      config.limits.dailyTasks
+    );
+  } catch (err) {
+    if (err instanceof ProviderRateLimitError || err instanceof ProviderUnavailableError) {
+      if (err.reservationId) {
+        rollbackBudgetReservation(root, err.reservationId);
+      }
+      const retryAfterMs = err.retryAfterMs || 60000;
+      const status = err instanceof ProviderRateLimitError ? "RATE_LIMITED" : "PROVIDER_UNAVAILABLE";
+      const backoffSec = Math.ceil(retryAfterMs / 1000);
+      console.warn(`[PROVIDER_INFRASTRUCTURE_FAILURE] ${err.name}: ${err.message}. Recommended backoff: ${backoffSec}s.`);
+      return {
+        ok: false,
+        status,
+        error: err.message,
+        retryAfterMs,
+        providerError: true,
+      };
+    }
+    throw err;
+  }
 }
 
-export async function run(opts = {}) {
-  const root = opts.root || process.cwd();
-  const config = opts.config || loadConfig(root);
-  const concurrency = opts.concurrency || config.limits.concurrency || 1;
+export async function run(tasksOrOpts = {}, opts = {}) {
+  let tasks = null;
+  let options = opts;
+  if (Array.isArray(tasksOrOpts)) {
+    tasks = tasksOrOpts;
+    options = opts || {};
+  } else if (tasksOrOpts && typeof tasksOrOpts === "object") {
+    options = tasksOrOpts;
+  }
+
+  const root = options.root || process.cwd();
+  const config = options.config || loadConfig(root);
+  const concurrency = options.concurrency || config.limits.concurrency || 1;
+  const isDry = options.dryRun !== undefined ? options.dryRun : (process.env.JULES_DRY_RUN === "true" || process.env.JULES_DRY_RUN === "1");
   const queueDir = getQueueDir(root);
   const completedDir = join(queueDir, "completed");
   ensureDir(completedDir);
 
-  const files = readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir));
+  let filesToProcess = [];
+  if (Array.isArray(tasks)) {
+    filesToProcess = tasks.map((t) => (typeof t === "string" ? t : t.id || t.file || t.title));
+  } else {
+    filesToProcess = readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir));
+  }
+
   const results = [];
 
-  for (let i = 0; i < files.length; i += concurrency) {
-    const batch = files.slice(i, i + concurrency);
+  for (let i = 0; i < filesToProcess.length; i += concurrency) {
+    const batch = filesToProcess.slice(i, i + concurrency);
     await Promise.all(
-      batch.map(async (file) => {
-        const srcPath = join(queueDir, file);
+      batch.map(async (fileOrItem) => {
+        const fileName = typeof fileOrItem === "string" ? fileOrItem : fileOrItem.id || fileOrItem.file;
+        const srcPath = join(queueDir, fileName);
         try {
-          const content = readFileSync(srcPath, "utf-8");
-          const task = { title: file, prompt: content };
-          const session = await dispatch(task, { root, config, dryRun: opts.dryRun });
-          const dstPath = join(completedDir, file);
-          renameSync(srcPath, dstPath);
-          appendLedger({ event: "task_completed", file, session }, root);
-          results.push({ file, ok: true, session });
+          let prompt = typeof fileOrItem === "object" && fileOrItem.prompt ? fileOrItem.prompt : "";
+          if (!prompt && existsSync(srcPath)) {
+            prompt = readFileSync(srcPath, "utf-8");
+          }
+          const task = { title: fileName, prompt };
+          const session = await dispatch(task, { root, config, dryRun: isDry });
+          const dstPath = join(completedDir, fileName);
+          if (existsSync(srcPath)) {
+            renameSync(srcPath, dstPath);
+          }
+          appendLedger({ event: "task_completed", file: fileName, session }, root);
+          results.push({ file: fileName, ok: true, session });
         } catch (err) {
-          results.push({ file, ok: false, error: err.message });
+          results.push({ file: fileName, ok: false, error: err.message });
         }
       })
     );

package/src/envelope.mjs

@@ -1,4 +1,4 @@
-import { git, resolveBase } from "./git.mjs";
+import { git, runCmd, resolveBase } from "./git.mjs";
 import { checkScope } from "./security.mjs";
 import { normalizeScope } from "./config.mjs";
 import { existsSync } from "node:fs";
@@ -70,8 +70,8 @@ export function validateEnvelope(envelope = {}, opts = {}) {
       const absPath = join(root, relPath);
       let existsInGit = false;
       if (resolvedBase) {
-        const catRes = git(["cat-file", "-e", `${resolvedBase}:${relPath}`], { cwd: root, ignoreError: true });
-        existsInGit = typeof catRes === "string" && catRes.trim() !== "";
+        const catRes = runCmd(["git", "cat-file", "-e", `${resolvedBase}:${relPath}`], { cwd: root, ignoreError: true });
+        existsInGit = catRes.status === 0;
       }
       const existsOnDisk = existsSync(absPath);
       if (!existsInGit && !existsOnDisk) {

package/src/flaky-ledger.mjs

@@ -83,8 +83,6 @@ export function readVerifyRuns(root, testCmd = null) {
   }
 }
 
-export const getVerifyRuns = readVerifyRuns;
-
 /**
  * Evaluates flaky test verdict using a sliding window of the last n <= 10 runs.
  */

package/src/git.mjs

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { sep } from "node:path";
+import { normalizePath } from "./config.mjs";
 import { journalIntent, journalDone } from "./journal.mjs";
 
 export const NET_GUARD_PRELOAD_URL = new URL("./preload-net-guard.mjs", import.meta.url).href;
@@ -13,11 +13,6 @@ export class GateError extends Error {
   }
 }
 
-function normalizePath(p) {
-  if (!p || typeof p !== "string") return "";
-  return p.split(sep).join("/").replace(/\\/g, "/");
-}
-
 const DEFAULT_TIMEOUT = 10 * 60 * 1000; // 10 minutes
 const DEFAULT_MAX_BUFFER = 10 * 1024 * 1024; // 10 MB
 

package/src/mcp.mjs

@@ -9,7 +9,7 @@ import { ProgressBus } from "./mcp-progress.mjs";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
-  version: "0.23.0",
+  version: "0.25.0",
 };
 
 export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling

package/src/merge-verify.mjs

@@ -31,14 +31,14 @@ export function mergeVerifyChain(mergedText, fileName, root = process.cwd()) {
       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];
+      const localTsc = join(root, "node_modules", ".bin", "tsc");
+      const hasLocalTsc = existsSync(localTsc);
+      if (hasTsConfig && hasLocalTsc) {
+        cmd = localTsc;
+        args = ["--noEmit", tempFilePath];
         tool = "tsc --noEmit";
       } else {
-        cmd = "node";
-        args = ["--check", tempFilePath];
-        tool = "node --check";
+        return { ok: true, tool: "ts-skipped-no-tsconfig" };
       }
     } else {
       // JS, MJS, CJS or default
@@ -47,7 +47,7 @@ export function mergeVerifyChain(mergedText, fileName, root = process.cwd()) {
       tool = "node --check";
     }
 
-    const res = spawnSync(cmd, args, { encoding: "utf8" });
+    const res = spawnSync(cmd, args, { encoding: "utf8", timeout: 120000 });
     const ok = res.status === 0;
 
     return {

package/src/provider.mjs

@@ -31,6 +31,45 @@ export const CODEX_PRESET = {
   promptViaStdin: false,
 };
 
+export class ProviderRateLimitError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "ProviderRateLimitError";
+    this.retryAfterMs = opts.retryAfterMs ?? 60000;
+    this.status = opts.status || 429;
+  }
+}
+
+export class ProviderUnavailableError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "ProviderUnavailableError";
+    this.status = opts.status || 503;
+    this.retryAfterMs = opts.retryAfterMs;
+  }
+}
+
+export class ProviderSchemaError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "ProviderSchemaError";
+    this.status = opts.status;
+  }
+}
+
+export function parseRetryAfter(header) {
+  if (!header) return null;
+  const seconds = Number(header);
+  if (!isNaN(seconds)) {
+    return Math.max(0, Math.round(seconds * 1000));
+  }
+  const dateMs = Date.parse(header);
+  if (!isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+  return null;
+}
+
 function interpolateString(template, data) {
   if (typeof template !== "string") return template;
   return template.replace(/\{(\w+)\}/g, (_, key) => data[key] ?? "");
@@ -111,20 +150,63 @@ export function createProvider(spec = "jules", config = {}) {
           body = JSON.stringify(data);
         }
 
-        const res = await fetch(url, {
-          method: providerSpec.method || "POST",
-          headers,
-          body,
-        });
+        const timeoutMs = ctx.timeoutMs || config.timeoutMs || providerSpec.timeoutMs || 120_000;
+        let res;
+        try {
+          res = await fetch(url, {
+            method: providerSpec.method || "POST",
+            headers,
+            body,
+            signal: AbortSignal.timeout(timeoutMs),
+          });
+        } catch (err) {
+          if (err.name === "TimeoutError" || err.name === "AbortError" || err.code === "ABORT_ERR") {
+            throw new ProviderUnavailableError(`Provider HTTP Timeout (${timeoutMs}ms): ${err.message}`, {
+              status: 504,
+            });
+          }
+          throw err;
+        }
 
         if (!res.ok) {
           const text = await res.text();
           const cleanText = text.slice(0, 500);
           const sanitizedText = rawToken ? cleanText.split(rawToken).join("[REDACTED]") : cleanText;
+          const retryAfterHeader = res.headers ? res.headers.get("retry-after") : null;
+          const retryAfterMs = parseRetryAfter(retryAfterHeader);
+
+          if (res.status === 429) {
+            throw new ProviderRateLimitError(`Provider HTTP Error (429): ${sanitizedText}`, {
+              retryAfterMs: retryAfterMs ?? 60000,
+              status: 429,
+            });
+          }
+
+          if (res.status >= 500 && res.status < 600) {
+            throw new ProviderUnavailableError(`Provider HTTP Error (${res.status}): ${sanitizedText}`, {
+              status: res.status,
+              retryAfterMs: retryAfterMs ?? undefined,
+            });
+          }
+
           throw new Error(`Provider HTTP Error (${res.status}): ${sanitizedText}`);
         }
 
-        const json = await res.json();
+        let json;
+        try {
+          json = await res.json();
+        } catch (err) {
+          throw new ProviderSchemaError(`Provider Payload Error: Invalid JSON response: ${err.message}`, {
+            status: res.status,
+          });
+        }
+
+        if (!json || typeof json !== "object") {
+          throw new ProviderSchemaError("Provider Payload Error: Expected JSON object response", {
+            status: res.status,
+          });
+        }
+
         return {
           id: json.id || json.name || "http-session",
           status: json.state || "active",

package/src/state.mjs

@@ -189,19 +189,31 @@ export function checkDailyBudget(arg1 = resolveRoot(), arg2 = 300) {
     const content = readFileSync(filePath, "utf-8");
     const lines = content.split("\n").filter(Boolean);
     let count = 0;
+    const activeIds = new Set();
     for (const line of lines) {
       try {
         const entry = JSON.parse(line);
         if (entry && entry.event === "budget_reserved") {
-          count++;
+          if (entry.reservationId) {
+            activeIds.add(entry.reservationId);
+          } else {
+            count++;
+          }
+        } else if (entry && (entry.event === "budget_rolled_back" || entry.event === "budget_released")) {
+          if (entry.reservationId) {
+            activeIds.delete(entry.reservationId);
+          } else {
+            count = Math.max(0, count - 1);
+          }
         }
       } catch (_) {}
     }
+    const used = count + activeIds.size;
     return {
-      ok: count < limit,
-      used: count,
+      ok: used < limit,
+      used,
       budget: limit,
-      remaining: Math.max(0, limit - count),
+      remaining: Math.max(0, limit - used),
     };
   } catch (_) {
     return { ok: true, used: 0, budget: limit, remaining: limit };
@@ -226,6 +238,7 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
     const filePath = join(stateDir, `ledger-${dateStr}.jsonl`);
 
     let count = 0;
+    const activeIds = new Set();
     let prevHash = "0".repeat(64);
 
     if (existsSync(filePath)) {
@@ -236,7 +249,17 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
           try {
             const entry = JSON.parse(line);
             if (entry && entry.event === "budget_reserved") {
-              count++;
+              if (entry.reservationId) {
+                activeIds.add(entry.reservationId);
+              } else {
+                count++;
+              }
+            } else if (entry && (entry.event === "budget_rolled_back" || entry.event === "budget_released")) {
+              if (entry.reservationId) {
+                activeIds.delete(entry.reservationId);
+              } else {
+                count = Math.max(0, count - 1);
+              }
             }
             if (entry && entry.hash) {
               prevHash = entry.hash;
@@ -246,8 +269,9 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
       } catch (_) {}
     }
 
-    if (count >= limit) {
-      throw new BudgetError(`Daily budget exhausted (${count}/${limit} tasks executed)`);
+    const used = count + activeIds.size;
+    if (used >= limit) {
+      throw new BudgetError(`Daily budget exhausted (${used}/${limit} tasks executed)`);
     }
 
     const timestamp = new Date().toISOString();
@@ -267,8 +291,8 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
     return {
       ok: true,
       reservationId,
-      remaining: Math.max(0, limit - (count + 1)),
-      used: count + 1,
+      remaining: Math.max(0, limit - (used + 1)),
+      used: used + 1,
     };
   }, opts);
 }
@@ -282,6 +306,11 @@ export function commitBudgetReservation(rootOrOpts = resolveRoot(), reservationI
   return appendLedger({ event: "budget_committed", reservationId }, root);
 }
 
+export function rollbackBudgetReservation(rootOrOpts = resolveRoot(), reservationId = "") {
+  const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
+  return appendLedger({ event: "budget_rolled_back", reservationId }, root);
+}
+
 export async function withBudget(fn, root = resolveRoot(), limit = 300) {
   const reservation = reserveBudget(root, limit);
   try {
@@ -289,6 +318,9 @@ export async function withBudget(fn, root = resolveRoot(), limit = 300) {
     commitBudgetReservation(root, reservation.reservationId);
     return result;
   } catch (err) {
+    if (err && typeof err === "object") {
+      err.reservationId = reservation.reservationId;
+    }
     appendLedger({ event: "budget_reservation_failed", reservationId: reservation.reservationId, error: err.message }, root);
     throw err;
   }
@@ -349,8 +381,9 @@ export function isPidAlive(pid, expectedStartTime = null) {
   return true;
 }
 
-export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveRoot()) {
-  const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
+export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveRoot(), opts = {}) {
+  const root = typeof rootOrOpts === "string" ? rootOrOpts : (rootOrOpts?.root || resolveRoot());
+  const branch = (typeof rootOrOpts === "object" && rootOrOpts?.branch) || opts?.branch || process.env.JULES_BRANCH || process.env.BRANCH_NAME || "";
   const lockDir = getLockDir(root);
   const lockFile = join(lockDir, `${taskId}.json`);
 
@@ -375,6 +408,7 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
   const payload = {
     agent: agentName,
     taskId,
+    branch,
     files,
     pid: process.pid,
     processStartTime: startTime,

package/src/telemetry.mjs

@@ -1,6 +1,7 @@
 import {
   openSync,
   writeSync,
+  readSync,
   closeSync,
   readFileSync,
   existsSync,
@@ -16,6 +17,37 @@ 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);
 
+/**
+ * Reads up to 64 KB from EOF of target log segment to extract true tail hash.
+ */
+function readTailHash(filePath, bufferSize = 64 * 1024) {
+  if (!existsSync(filePath)) return null;
+  try {
+    const stat = statSync(filePath);
+    if (stat.size === 0) return null;
+    const readSize = Math.min(stat.size, bufferSize);
+    const position = stat.size - readSize;
+    const fd = openSync(filePath, "r");
+    const buf = Buffer.alloc(readSize);
+    try {
+      readSync(fd, buf, 0, readSize, position);
+    } finally {
+      closeSync(fd);
+    }
+    const content = buf.toString("utf-8");
+    const lines = content.split("\n").filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const obj = JSON.parse(lines[i]);
+        if (obj && typeof obj.hash === "string") {
+          return obj.hash;
+        }
+      } catch (_) {}
+    }
+  } catch (_) {}
+  return null;
+}
+
 /**
  * Returns telemetry file paths for a given date string sorted by segment index.
  */
@@ -50,18 +82,10 @@ function coldScanTelemetry(stateDir, dateStr) {
   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 (_) {}
+      const tailHash = readTailHash(seg.path);
+      if (tailHash) {
+        return { hash: tailHash, segment: seg.index };
+      }
     }
   }
 
@@ -70,7 +94,7 @@ function coldScanTelemetry(stateDir, dateStr) {
 
 /**
  * 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.
+ * Uses .head atomic cache with true tail reconciliation for O(1) constant-time appends.
  *
  * @param {string} [rootOrOpts]
  * @param {string} kind
@@ -102,18 +126,30 @@ export function appendTelemetry(rootOrOpts = resolveRoot(), kind = "event", fiel
       } 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);
 
+    // Reconcile .head hash against true log tail (reading last 64 KB from EOF)
+    const tailHash = readTailHash(activeFilePath);
+    if (tailHash) {
+      if (tailHash !== prevHash) {
+        prevHash = tailHash;
+      }
+      headValid = true;
+    } else if (!headValid) {
+      const recovered = coldScanTelemetry(stateDir, dateStr);
+      prevHash = recovered.hash;
+      activeSegmentIndex = recovered.segment;
+      activeFileName =
+        activeSegmentIndex === 0
+          ? `telemetry-${dateStr}.jsonl`
+          : `telemetry-${dateStr}-${activeSegmentIndex}.jsonl`;
+      activeFilePath = join(stateDir, activeFileName);
+    }
+
     if (existsSync(activeFilePath)) {
       try {
         const stat = statSync(activeFilePath);

package/.agent/jules-queue/README.md

@@ -1,30 +0,0 @@
-# Jules Task Queue Directory
-
-Drop markdown task specification files here (e.g. `TASK-001-feature-name.md`) to queue tasks for background execution by Google Jules.
-
-### File Format Example
-
-```markdown
-# TASK-001: Implement User Rate Limiting
-
-## Objective
-Implement sliding window rate limiting for public API routes.
-
-## Execution Rules
-- Use Redis / memory store for tracking hit counts.
-- Must return HTTP 429 Too Many Requests when limit is exceeded.
-- Must pass `npm test` before submitting PR.
-```
-
-Process all queued tasks in batch:
-
-```bash
-agentctl queue
-# or npm run jules:queue
-```
-
-Or dispatch a single task using `agentctl dispatch`:
-
-```bash
-agentctl dispatch --title "TASK-001 Rate Limiting" --prompt "$(cat .agent/jules-queue/TASK-001-rate-limiting.md)"
-```