@runfusion/fusion 0.9.2 → 0.9.3

package/dist/extension.js

@@ -890,6 +890,12 @@ function hasAgentIdentity(agent) {
   if (!agent) return false;
   return !!(agent.soul?.trim() || agent.instructionsText?.trim() || agent.instructionsPath?.trim() || agent.memory?.trim());
 }
+function getDefaultHeartbeatProcedurePath(agentId) {
+  if (!agentId || typeof agentId !== "string") {
+    throw new Error("getDefaultHeartbeatProcedurePath requires a non-empty agentId");
+  }
+  return `.fusion/agents/${agentId}/HEARTBEAT.md`;
+}
 function agentToConfigSnapshot(agent) {
   return {
     name: agent.name,
@@ -4370,8 +4376,9 @@ CREATE INDEX IF NOT EXISTS idxTodoItemsSortOrder ON todo_items(listId, sortOrder
 });
 
 // ../core/src/agent-store.ts
-import { mkdir, readFile, writeFile, readdir, unlink, rename } from "node:fs/promises";
-import { basename, join as join3, resolve as resolve2 } from "node:path";
+import { mkdir, readFile, writeFile, readdir, unlink, rename, access } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { basename, dirname, join as join3, resolve as resolve2 } from "node:path";
 import { randomUUID, randomBytes, createHash } from "node:crypto";
 import { EventEmitter } from "node:events";
 function resolveCreationRuntimeConfig(incoming, metadata) {
@@ -4427,9 +4434,75 @@ var init_agent_store = __esm({
        * Should be called before other operations.
        */
       async init() {
-        const _ = this.db;
+        void this.db;
         await mkdir(this.agentsDir, { recursive: true });
         await this.importLegacyFileDataOnce();
+        await this.migrateHeartbeatProcedurePathOnce();
+      }
+      /**
+       * One-shot migration that re-points every non-ephemeral agent off the
+       * legacy shared `.fusion/HEARTBEAT.md` path onto their own per-agent
+       * `.fusion/agents/<id>/HEARTBEAT.md` file. The legacy file's contents
+       * are copied to the new location when present so operator edits are
+       * preserved across the upgrade. The legacy file itself is left in place
+       * — the migration is non-destructive in case the operator wants a
+       * reference copy.
+       *
+       * Idempotent: tracks completion in the `__meta` table and short-circuits
+       * on subsequent calls. Failures during file copy are logged via the
+       * legacy console (no log dependency in core) and do not block startup —
+       * the agent's `heartbeatProcedurePath` is still flipped, and the engine's
+       * heartbeat resolver will fall back to the built-in template until the
+       * file is seeded on next dashboard interaction.
+       */
+      async migrateHeartbeatProcedurePathOnce() {
+        const migrationKey = "heartbeatProcedurePathPerAgent";
+        const migrationVersion = "1";
+        const row = this.db.prepare("SELECT value FROM __meta WHERE key = ?").get(migrationKey);
+        if (row?.value === migrationVersion) {
+          return;
+        }
+        let legacyContent = null;
+        try {
+          legacyContent = await readFile(join3(this.rootDir, "HEARTBEAT.md"), "utf-8");
+        } catch {
+          legacyContent = null;
+        }
+        const agents = await this.listAgents({ includeEphemeral: false });
+        let migratedCount = 0;
+        for (const agent of agents) {
+          if (agent.heartbeatProcedurePath !== DEFAULT_HEARTBEAT_PROCEDURE_PATH) {
+            continue;
+          }
+          const newRelPath = getDefaultHeartbeatProcedurePath(agent.id);
+          const newAbsPath = join3(this.rootDir, "..", newRelPath);
+          if (legacyContent !== null) {
+            try {
+              await mkdir(dirname(newAbsPath), { recursive: true });
+              try {
+                await access(newAbsPath, fsConstants.F_OK);
+              } catch {
+                await writeFile(newAbsPath, legacyContent, "utf-8");
+              }
+            } catch {
+            }
+          }
+          const updated = {
+            ...agent,
+            heartbeatProcedurePath: newRelPath,
+            updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          await this.writeAgent(updated);
+          migratedCount += 1;
+        }
+        this.db.prepare(`
+      INSERT INTO __meta (key, value)
+      VALUES (?, ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `).run(migrationKey, migrationVersion);
+        if (migratedCount > 0) {
+          this.db.bumpLastModified();
+        }
       }
       /**
        * One-way migration helper for projects that still have legacy agent JSON
@@ -4562,7 +4635,7 @@ var init_agent_store = __esm({
         const metadata = input.metadata ?? {};
         const runtimeConfig = resolveCreationRuntimeConfig(input.runtimeConfig, metadata);
         const ephemeral = isEphemeralAgent({ metadata, name: input.name, role: input.role, reportsTo: input.reportsTo });
-        const resolvedHeartbeatProcedurePath = input.heartbeatProcedurePath ?? (ephemeral ? void 0 : DEFAULT_HEARTBEAT_PROCEDURE_PATH);
+        const resolvedHeartbeatProcedurePath = input.heartbeatProcedurePath ?? (ephemeral ? void 0 : getDefaultHeartbeatProcedurePath(agentId));
         const agent = {
           id: agentId,
           name: input.name.trim(),
@@ -6496,7 +6569,7 @@ var init_task_priority = __esm({
 
 // ../core/src/global-settings.ts
 import { homedir } from "node:os";
-import { dirname, join as join5 } from "node:path";
+import { dirname as dirname2, join as join5 } from "node:path";
 import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3, rename as rename2, chmod } from "node:fs/promises";
 import { existsSync as existsSync3, mkdirSync as mkdirSync2, renameSync } from "node:fs";
 function getHomeDir() {
@@ -6526,7 +6599,7 @@ function resolveGlobalDir(dir) {
   const legacyDir = legacyGlobalDir();
   if (existsSync3(legacyDir)) {
     try {
-      mkdirSync2(dirname(preferredDir), { recursive: true });
+      mkdirSync2(dirname2(preferredDir), { recursive: true });
       renameSync(legacyDir, preferredDir);
       return preferredDir;
     } catch {
@@ -6536,7 +6609,7 @@ function resolveGlobalDir(dir) {
   const legacyDirOriginal = legacyGlobalDirOriginal();
   if (existsSync3(legacyDirOriginal)) {
     try {
-      mkdirSync2(dirname(preferredDir), { recursive: true });
+      mkdirSync2(dirname2(preferredDir), { recursive: true });
       renameSync(legacyDirOriginal, preferredDir);
       return preferredDir;
     } catch {
@@ -12318,11 +12391,11 @@ var init_todo_store = __esm({
 
 // ../core/src/app-version.ts
 import { readFileSync } from "node:fs";
-import { join as join9, dirname as dirname2 } from "node:path";
+import { join as join9, dirname as dirname3 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function getAppVersion() {
   if (cachedVersion !== null) return cachedVersion;
-  const __dirname2 = dirname2(fileURLToPath2(import.meta.url));
+  const __dirname2 = dirname3(fileURLToPath2(import.meta.url));
   let currentDir = __dirname2;
   for (let i = 0; i < 10; i++) {
     try {
@@ -12334,7 +12407,7 @@ function getAppVersion() {
       }
     } catch {
     }
-    const parentDir = dirname2(currentDir);
+    const parentDir = dirname3(currentDir);
     if (parentDir === currentDir) break;
     currentDir = parentDir;
   }
@@ -16341,7 +16414,7 @@ __export(check_disk_space_exports, {
   getFirstExistingParentPath: () => getFirstExistingParentPath
 });
 import { execFile } from "node:child_process";
-import { access } from "node:fs/promises";
+import { access as access2 } from "node:fs/promises";
 import { release } from "node:os";
 import { normalize, sep as sep2 } from "node:path";
 import { platform } from "node:process";
@@ -16378,7 +16451,7 @@ async function hasPowerShell3(dependencies) {
 function checkDiskSpace(directoryPath, dependencies = {
   platform,
   release: release(),
-  fsAccess: access,
+  fsAccess: access2,
   pathNormalize: normalize,
   pathSep: sep2,
   cpExecFile: promisify(execFile)
@@ -18524,7 +18597,7 @@ __export(migration_exports, {
 });
 import { existsSync as existsSync9 } from "node:fs";
 import { homedir as homedir2, tmpdir } from "node:os";
-import { isAbsolute as isAbsolute3, join as join12, resolve as resolve5, basename as basename3, dirname as dirname3 } from "node:path";
+import { isAbsolute as isAbsolute3, join as join12, resolve as resolve5, basename as basename3, dirname as dirname4 } from "node:path";
 function getHomeDir2() {
   return process.env.HOME || process.env.USERPROFILE || homedir2();
 }
@@ -18624,7 +18697,7 @@ var init_migration = __esm({
         const visited = /* @__PURE__ */ new Set();
         let current = resolve5(startDir);
         const home = getHomeDir2();
-        const root = dirname3(current) === current ? current : "/";
+        const root = dirname4(current) === current ? current : "/";
         const systemTmp = resolve5(tmpdir());
         while (current !== home && current !== root && current !== systemTmp) {
           if (visited.has(current)) break;
@@ -18638,7 +18711,7 @@ var init_migration = __esm({
             });
             break;
           }
-          const parent = dirname3(current);
+          const parent = dirname4(current);
           if (parent === current) break;
           current = parent;
         }
@@ -28939,9 +29012,9 @@ __export(memory_backend_exports, {
   writeMemory: () => writeMemory,
   writeProjectMemoryFile: () => writeProjectMemoryFile
 });
-import { readFile as readFile6, writeFile as writeFile5, mkdir as mkdir6, access as access2, constants, readdir as readdir4, stat as stat2 } from "node:fs/promises";
+import { readFile as readFile6, writeFile as writeFile5, mkdir as mkdir6, access as access3, constants, readdir as readdir4, stat as stat2 } from "node:fs/promises";
 import { existsSync as existsSync11 } from "node:fs";
-import { basename as basename4, dirname as dirname4, isAbsolute as isAbsolute4, join as join15, normalize as normalize2, relative, resolve as resolve6, sep as sep3 } from "node:path";
+import { basename as basename4, dirname as dirname5, isAbsolute as isAbsolute4, join as join15, normalize as normalize2, relative, resolve as resolve6, sep as sep3 } from "node:path";
 import { createHash as createHash3 } from "node:crypto";
 function shouldSkipBackgroundQmdRefresh() {
   return (process.env.VITEST === "true" || process.env.NODE_ENV === "test") && process.env.FUSION_ENABLE_QMD_REFRESH_IN_TESTS !== "1";
@@ -29101,7 +29174,7 @@ async function readProjectMemoryFileContent(rootDir, path2) {
 }
 async function writeProjectMemoryFile(rootDir, path2, content) {
   const { absPath } = resolveMemoryFilePath(rootDir, path2);
-  await mkdir6(dirname4(absPath), { recursive: true });
+  await mkdir6(dirname5(absPath), { recursive: true });
   const tmpPath = `${absPath}.tmp`;
   await writeFile5(tmpPath, content, "utf-8");
   const { rename: rename6 } = await import("node:fs/promises");
@@ -29220,7 +29293,7 @@ async function readAgentMemoryFile(rootDir, agentId, path2) {
 }
 async function writeAgentMemoryFile(rootDir, agentId, path2, content) {
   const { absPath } = await resolveAgentMemoryFilePath(rootDir, agentId, path2);
-  await mkdir6(dirname4(absPath), { recursive: true });
+  await mkdir6(dirname5(absPath), { recursive: true });
   const tmpPath = `${absPath}.tmp`;
   await writeFile5(tmpPath, content, "utf-8");
   const { rename: rename6 } = await import("node:fs/promises");
@@ -29366,7 +29439,7 @@ function normalizeQmdSearchResultPath(rootDir, rawPath) {
   }
   const lowerCandidate = candidate.toLowerCase();
   const normalizedBaseName = basename4(candidate).toLowerCase();
-  const normalizedDirName = dirname4(lowerCandidate).replace(/\\/g, "/");
+  const normalizedDirName = dirname5(lowerCandidate).replace(/\\/g, "/");
   if (normalizedBaseName === "memory.md" && (normalizedDirName === ".fusion" || normalizedDirName.endsWith("/.fusion"))) {
     return `${MEMORY_WORKSPACE_PATH}/${MEMORY_LONG_TERM_FILENAME}`;
   }
@@ -29690,7 +29763,7 @@ var init_memory_backend = __esm({
       }
       async exists(rootDir) {
         try {
-          await access2(this.getLongTermPath(rootDir), constants.R_OK);
+          await access3(this.getLongTermPath(rootDir), constants.R_OK);
           return true;
         } catch {
           return false;
@@ -32737,6 +32810,16 @@ ${newTask.description}
           } else if (updates.sessionFile !== void 0) {
             task.sessionFile = updates.sessionFile;
           }
+          if (updates.executionStartedAt === null) {
+            task.executionStartedAt = void 0;
+          } else if (updates.executionStartedAt !== void 0) {
+            task.executionStartedAt = updates.executionStartedAt;
+          }
+          if (updates.executionCompletedAt === null) {
+            task.executionCompletedAt = void 0;
+          } else if (updates.executionCompletedAt !== void 0) {
+            task.executionCompletedAt = updates.executionCompletedAt;
+          }
           if (updates.workflowStepResults === null) {
             task.workflowStepResults = void 0;
           } else if (updates.workflowStepResults !== void 0) {
@@ -36273,7 +36356,7 @@ var init_dispatcher = __esm({
 });
 
 // ../core/src/plugin-loader.ts
-import { basename as basename6, dirname as dirname5, extname, isAbsolute as isAbsolute6, resolve as resolve8 } from "node:path";
+import { basename as basename6, dirname as dirname6, extname, isAbsolute as isAbsolute6, resolve as resolve8 } from "node:path";
 import { copyFile, rm } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 import { EventEmitter as EventEmitter15 } from "node:events";
@@ -36430,7 +36513,7 @@ var init_plugin_loader = __esm({
           moduleImportVersion += 1;
           const ext = extname(path2);
           const baseName = basename6(path2, ext);
-          const reloadedPath = resolve8(dirname5(path2), `.${baseName}.reload-${moduleImportVersion}${ext}`);
+          const reloadedPath = resolve8(dirname6(path2), `.${baseName}.reload-${moduleImportVersion}${ext}`);
           await copyFile(path2, reloadedPath);
           try {
             mod = await import(pathToFileURL(reloadedPath).href);
@@ -38055,7 +38138,7 @@ var init_mission_types = __esm({
 // ../core/src/memory-insights.ts
 import { readFile as readFile10, writeFile as writeFile8, mkdir as mkdir9 } from "node:fs/promises";
 import { existsSync as existsSync16 } from "node:fs";
-import { dirname as dirname6, join as join19 } from "node:path";
+import { dirname as dirname7, join as join19 } from "node:path";
 async function readWorkingMemory(rootDir) {
   const filePath = join19(rootDir, MEMORY_WORKING_PATH);
   if (!existsSync16(filePath)) {
@@ -38080,7 +38163,7 @@ async function writeInsightsMemory(rootDir, content) {
 }
 async function writeWorkingMemory(rootDir, content) {
   const filePath = join19(rootDir, MEMORY_WORKING_PATH);
-  const dir = dirname6(filePath);
+  const dir = dirname7(filePath);
   if (!existsSync16(dir)) {
     await mkdir9(dir, { recursive: true });
   }
@@ -50099,6 +50182,7 @@ __export(src_exports, {
   getCurrentRepo: () => getCurrentRepo,
   getDefaultDailyMemoryScaffold: () => getDefaultDailyMemoryScaffold,
   getDefaultDreamsScaffold: () => getDefaultDreamsScaffold,
+  getDefaultHeartbeatProcedurePath: () => getDefaultHeartbeatProcedurePath,
   getDefaultInsightsTemplate: () => getDefaultInsightsTemplate,
   getDefaultLongTermMemoryScaffold: () => getDefaultLongTermMemoryScaffold,
   getDefaultMemoryScaffold: () => getDefaultMemoryScaffold,
@@ -51951,7 +52035,7 @@ import { existsSync as existsSync21, readFileSync as readFileSync7 } from "node:
 import { exec } from "node:child_process";
 import { promisify as promisify2 } from "node:util";
 import { createRequire as createRequire2 } from "node:module";
-import { basename as basename7, dirname as dirname7, join as join26, relative as relative3, isAbsolute as isAbsolute7, resolve as resolve11 } from "node:path";
+import { basename as basename7, dirname as dirname8, join as join26, relative as relative3, isAbsolute as isAbsolute7, resolve as resolve11 } from "node:path";
 import {
   createAgentSession,
   createBashTool,
@@ -52346,7 +52430,7 @@ function siblingAgentDir(agentDir, siblingRoot) {
   if (basename7(agentDir) !== "agent") {
     return void 0;
   }
-  return join26(dirname7(dirname7(agentDir)), siblingRoot, "agent");
+  return join26(dirname8(dirname8(agentDir)), siblingRoot, "agent");
 }
 function createReadOnlyPiSettingsView(cwd, agentDir) {
   const projectRoot = resolvePiExtensionProjectRoot(cwd);
@@ -52386,7 +52470,7 @@ function resolveVendoredClaudeCliEntry() {
     if (!Array.isArray(extensions) || extensions.length === 0) return null;
     const entry = extensions[0];
     if (typeof entry !== "string" || entry.length === 0) return null;
-    const path2 = resolve11(dirname7(pkgJsonPath), entry);
+    const path2 = resolve11(dirname8(pkgJsonPath), entry);
     return existsSync21(path2) ? path2 : null;
   } catch {
     return null;
@@ -53241,9 +53325,9 @@ var init_usage_limit_detector = __esm({
 });
 
 // ../engine/src/agent-instructions.ts
-import { readFile as readFile12, writeFile as writeFile11, mkdir as mkdir12, access as access3 } from "node:fs/promises";
-import { constants as fsConstants } from "node:fs";
-import { isAbsolute as isAbsolute8, resolve as resolve12, relative as relative4, normalize as normalize3, sep as sep5, dirname as dirname8 } from "node:path";
+import { readFile as readFile12, writeFile as writeFile11, mkdir as mkdir12, access as access4 } from "node:fs/promises";
+import { constants as fsConstants2 } from "node:fs";
+import { isAbsolute as isAbsolute8, resolve as resolve12, relative as relative4, normalize as normalize3, sep as sep5, dirname as dirname9 } from "node:path";
 function trimAndClamp(value, maxLength, label, agentId) {
   const trimmed = value.trim();
   if (!trimmed) {
@@ -53327,12 +53411,12 @@ async function ensureDefaultHeartbeatProcedureFile(rootDir, procedurePathRel, de
     return null;
   }
   try {
-    await access3(filePath, fsConstants.F_OK);
+    await access4(filePath, fsConstants2.F_OK);
     return filePath;
   } catch {
   }
   try {
-    await mkdir12(dirname8(filePath), { recursive: true });
+    await mkdir12(dirname9(filePath), { recursive: true });
     await writeFile11(filePath, defaultContent, "utf-8");
     log4.log(`Seeded default heartbeat procedure file at ${filePath}`);
     return filePath;
@@ -62211,8 +62295,12 @@ Lint, tests, and typecheck are also hard quality gates:
             throw new Error("task missing during workflow rerun bounce");
           }
           if (latestTask.column === "in-progress") {
+            const originalExecutionStartedAt = latestTask.executionStartedAt;
             await this.store.moveTask(taskId, "todo");
-            await this.store.updateTask(taskId, { worktree: worktreePath });
+            await this.store.updateTask(taskId, {
+              worktree: worktreePath,
+              executionStartedAt: originalExecutionStartedAt ?? null
+            });
             await this.store.moveTask(taskId, "in-progress");
             return "bounced";
           }
@@ -68559,7 +68647,7 @@ function isTickableState(state) {
 function isHeartbeatManaged(agent) {
   return !isEphemeralAgent(agent);
 }
-var HEARTBEAT_SYSTEM_PROMPT, HEARTBEAT_NO_TASK_SYSTEM_PROMPT, HEARTBEAT_PROCEDURE, heartbeatDoneParams, HeartbeatMonitor, HeartbeatTriggerScheduler;
+var HEARTBEAT_SYSTEM_PROMPT, HEARTBEAT_NO_TASK_SYSTEM_PROMPT, HEARTBEAT_PROCEDURE, heartbeatDoneParams, HeartbeatMonitor, OVERDUE_FIRE_JITTER_MS, HeartbeatTriggerScheduler;
 var init_agent_heartbeat = __esm({
   "../engine/src/agent-heartbeat.ts"() {
     "use strict";
@@ -69982,6 +70070,7 @@ ${taskDetail.prompt}` : "No PROMPT.md available.",
         this.onTerminated?.(tracked.agentId);
       }
     };
+    OVERDUE_FIRE_JITTER_MS = 5e3;
     HeartbeatTriggerScheduler = class _HeartbeatTriggerScheduler {
       store;
       callback;
@@ -70019,7 +70108,11 @@ ${taskDetail.prompt}` : "No PROMPT.md available.",
         this.unwatchAssignments();
         this.unwatchAgentLifecycle();
         for (const [agentId, timer] of this.timers) {
-          clearInterval(timer.handle);
+          if (timer.kind === "timeout") {
+            clearTimeout(timer.handle);
+          } else {
+            clearInterval(timer.handle);
+          }
           heartbeatLog.log(`Cleared timer for ${agentId}`);
         }
         this.timers.clear();
@@ -70035,10 +70128,19 @@ ${taskDetail.prompt}` : "No PROMPT.md available.",
       static DEFAULT_HEARTBEAT_INTERVAL_MS = 36e5;
       /**
        * Register an agent for timer-based heartbeat triggers.
+       *
+       * The first fire is phase-aligned to `options.lastHeartbeatAt + intervalMs`
+       * when supplied. This means a process restart resumes each agent's
+       * existing schedule rather than waiting up to a full interval before the
+       * first tick — the previous behavior caused agents on long intervals
+       * (e.g. 1h) to appear "overdue" in the UI for nearly a full interval after
+       * every dashboard restart even though nothing was actually wrong with them.
+       *
        * @param agentId - The agent ID
        * @param config - Per-agent heartbeat config
+       * @param options - Optional registration context (e.g., lastHeartbeatAt)
        */
-      registerAgent(agentId, config) {
+      registerAgent(agentId, config, options) {
         if (config.enabled === false) {
           this.unregisterAgent(agentId);
           return;
@@ -70052,12 +70154,13 @@ ${taskDetail.prompt}` : "No PROMPT.md available.",
         const intervalMs = Math.max(1e3, Math.round(rawIntervalMs));
         const registrationEpoch = (this.registrationEpochs.get(agentId) ?? 0) + 1;
         this.registrationEpochs.set(agentId, registrationEpoch);
-        this.applyTimerRegistration(agentId, intervalMs, 1, usingDefaultInterval);
+        const lastHeartbeatAt = options?.lastHeartbeatAt ?? null;
+        this.applyTimerRegistration(agentId, intervalMs, 1, usingDefaultInterval, lastHeartbeatAt);
         if (this.taskStore && typeof this.taskStore.getSettings === "function") {
-          void this.applyProjectMultiplierRegistration(agentId, intervalMs, usingDefaultInterval, registrationEpoch);
+          void this.applyProjectMultiplierRegistration(agentId, intervalMs, usingDefaultInterval, registrationEpoch, lastHeartbeatAt);
         }
       }
-      async applyProjectMultiplierRegistration(agentId, baseIntervalMs, usingDefaultInterval, expectedEpoch) {
+      async applyProjectMultiplierRegistration(agentId, baseIntervalMs, usingDefaultInterval, expectedEpoch, lastHeartbeatAt) {
         let multiplier = 1;
         try {
           const settings = await getHeartbeatMemorySettings(this.taskStore);
@@ -70071,23 +70174,68 @@ ${taskDetail.prompt}` : "No PROMPT.md available.",
         if (this.registrationEpochs.get(agentId) !== expectedEpoch) {
           return;
         }
-        this.applyTimerRegistration(agentId, baseIntervalMs, multiplier, usingDefaultInterval);
+        this.applyTimerRegistration(agentId, baseIntervalMs, multiplier, usingDefaultInterval, lastHeartbeatAt);
+      }
+      /**
+       * Compute the delay until the agent's next scheduled fire, given when it
+       * last heartbeat. When `lastHeartbeatAt` is missing or unparseable, falls
+       * back to a full-interval delay (matching the original behavior for
+       * agents that have never ticked). When the next fire is already overdue,
+       * returns a small randomized jitter to spread thundering herds at boot.
+       */
+      static computeInitialDelayMs(intervalMs, lastHeartbeatAt, now = Date.now()) {
+        if (!lastHeartbeatAt) {
+          return intervalMs;
+        }
+        const lastMs = Date.parse(lastHeartbeatAt);
+        if (!Number.isFinite(lastMs)) {
+          return intervalMs;
+        }
+        const remaining = lastMs + intervalMs - now;
+        if (remaining <= 0) {
+          return Math.floor(Math.random() * OVERDUE_FIRE_JITTER_MS);
+        }
+        return Math.min(remaining, intervalMs);
       }
-      applyTimerRegistration(agentId, baseIntervalMs, multiplier, usingDefaultInterval) {
+      applyTimerRegistration(agentId, baseIntervalMs, multiplier, usingDefaultInterval, lastHeartbeatAt) {
         const effectiveIntervalMs = Math.max(1e3, Math.round(baseIntervalMs * multiplier));
+        const initialDelayMs = _HeartbeatTriggerScheduler.computeInitialDelayMs(
+          effectiveIntervalMs,
+          lastHeartbeatAt
+        );
         this.clearAgentTimer(agentId);
-        const handle = setInterval(() => {
-          void this.onTimerTick(agentId, effectiveIntervalMs);
-        }, effectiveIntervalMs);
-        this.timers.set(agentId, { intervalMs: effectiveIntervalMs, handle });
+        const armSteadyInterval = () => {
+          const intervalHandle = setInterval(() => {
+            void this.onTimerTick(agentId, effectiveIntervalMs);
+          }, effectiveIntervalMs);
+          this.timers.set(agentId, {
+            intervalMs: effectiveIntervalMs,
+            kind: "interval",
+            handle: intervalHandle
+          });
+        };
+        if (initialDelayMs >= effectiveIntervalMs) {
+          armSteadyInterval();
+        } else {
+          const timeoutHandle = setTimeout(() => {
+            void this.onTimerTick(agentId, effectiveIntervalMs);
+            armSteadyInterval();
+          }, initialDelayMs);
+          this.timers.set(agentId, {
+            intervalMs: effectiveIntervalMs,
+            kind: "timeout",
+            handle: timeoutHandle
+          });
+        }
+        const phaseSuffix = lastHeartbeatAt ? `, first fire in ${initialDelayMs}ms (phase-aligned to lastHeartbeatAt)` : "";
         if (multiplier !== 1) {
           heartbeatLog.log(
-            `Registered timer for ${agentId} (every ${baseIntervalMs}ms, multiplier ${multiplier} \u2192 ${effectiveIntervalMs}ms effective)`
+            `Registered timer for ${agentId} (every ${baseIntervalMs}ms, multiplier ${multiplier} \u2192 ${effectiveIntervalMs}ms effective${phaseSuffix})`
           );
           return;
         }
         heartbeatLog.log(
-          usingDefaultInterval ? `Registered timer for ${agentId} (every ${effectiveIntervalMs}ms, default interval)` : `Registered timer for ${agentId} (every ${effectiveIntervalMs}ms)`
+          usingDefaultInterval ? `Registered timer for ${agentId} (every ${effectiveIntervalMs}ms, default interval${phaseSuffix})` : `Registered timer for ${agentId} (every ${effectiveIntervalMs}ms${phaseSuffix})`
         );
       }
       clearAgentTimer(agentId) {
@@ -70095,7 +70243,11 @@ ${taskDetail.prompt}` : "No PROMPT.md available.",
         if (!timer) {
           return;
         }
-        clearInterval(timer.handle);
+        if (timer.kind === "timeout") {
+          clearTimeout(timer.handle);
+        } else {
+          clearInterval(timer.handle);
+        }
         this.timers.delete(agentId);
       }
       static resolveHeartbeatMultiplier(rawMultiplier) {
@@ -70223,7 +70375,9 @@ ${taskDetail.prompt}` : "No PROMPT.md available.",
         if (this.timers.has(agent.id)) {
           return;
         }
-        this.registerAgent(agent.id, this.getAgentTimerConfig(agent));
+        this.registerAgent(agent.id, this.getAgentTimerConfig(agent), {
+          lastHeartbeatAt: agent.lastHeartbeatAt
+        });
         heartbeatLog.log(`Timer armed for ${agent.id} (${reason})`);
       }
       async syncTimerForAgentFromStore(agentId, reason) {
@@ -70236,7 +70390,9 @@ ${taskDetail.prompt}` : "No PROMPT.md available.",
           this.unregisterAgent(agentId);
           return;
         }
-        this.registerAgent(agent.id, this.getAgentTimerConfig(agent));
+        this.registerAgent(agent.id, this.getAgentTimerConfig(agent), {
+          lastHeartbeatAt: agent.lastHeartbeatAt
+        });
         heartbeatLog.log(`Timer refreshed for ${agent.id} (${reason})`);
       }
       didHeartbeatScheduleChange(revision) {
@@ -75076,11 +75232,15 @@ var init_in_process_runtime = __esm({
               for (const agent of agents) {
                 if (!isTimerManagedAgent(agent)) continue;
                 const rc = agent.runtimeConfig;
-                this.triggerScheduler.registerAgent(agent.id, {
-                  enabled: rc?.enabled,
-                  heartbeatIntervalMs: rc?.heartbeatIntervalMs,
-                  maxConcurrentRuns: rc?.maxConcurrentRuns
-                });
+                this.triggerScheduler.registerAgent(
+                  agent.id,
+                  {
+                    enabled: rc?.enabled,
+                    heartbeatIntervalMs: rc?.heartbeatIntervalMs,
+                    maxConcurrentRuns: rc?.maxConcurrentRuns
+                  },
+                  { lastHeartbeatAt: agent.lastHeartbeatAt }
+                );
                 registeredCount++;
               }
               if (agents.length > 0) {
@@ -75767,7 +75927,7 @@ var init_ipc_host = __esm({
 import { EventEmitter as EventEmitter20 } from "node:events";
 import { fork } from "node:child_process";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
-import { dirname as dirname9, join as join36 } from "node:path";
+import { dirname as dirname10, join as join36 } from "node:path";
 var HealthMonitor, ChildProcessRuntime;
 var init_child_process_runtime = __esm({
   "../engine/src/runtimes/child-process-runtime.ts"() {
@@ -75927,7 +76087,7 @@ var init_child_process_runtime = __esm({
        */
       getWorkerPath() {
         const isCompiled = !import.meta.url.endsWith(".ts");
-        const currentDir = dirname9(fileURLToPath3(import.meta.url));
+        const currentDir = dirname10(fileURLToPath3(import.meta.url));
         const workerFile = isCompiled ? "child-process-worker.js" : "child-process-worker.ts";
         return join36(currentDir, workerFile);
       }
@@ -77224,7 +77384,7 @@ var init_gridlock_detector = __esm({
 });
 
 // ../engine/src/remote-access/provider-adapters.ts
-import { accessSync, constants as fsConstants2 } from "node:fs";
+import { accessSync, constants as fsConstants3 } from "node:fs";
 function isAbsoluteOrPathLike(input) {
   return input.startsWith("/") || input.startsWith("./") || input.startsWith("../");
 }
@@ -77371,7 +77531,7 @@ var init_provider_adapters = __esm({
         if ("credentialsPath" in config && config.credentialsPath !== void 0) {
           assertNonEmpty(config.credentialsPath, "credentialsPath");
           if (isAbsoluteOrPathLike(config.credentialsPath)) {
-            accessSync(config.credentialsPath, fsConstants2.R_OK);
+            accessSync(config.credentialsPath, fsConstants3.R_OK);
           }
         }
       },
@@ -89328,7 +89488,7 @@ var init_exec_file = __esm({
 
 // ../dashboard/src/routes/register-project-routes.ts
 import * as fsPromises from "node:fs/promises";
-var access4, stat6, mkdir13, readdir8, rm2;
+var access5, stat6, mkdir13, readdir8, rm2;
 var init_register_project_routes = __esm({
   "../dashboard/src/routes/register-project-routes.ts"() {
     "use strict";
@@ -89337,7 +89497,7 @@ var init_register_project_routes = __esm({
     init_exec_file();
     init_project_store_resolver();
     ({
-      access: access4,
+      access: access5,
       stat: stat6,
       mkdir: mkdir13,
       readdir: readdir8,
@@ -89494,14 +89654,14 @@ var init_agent_generation = __esm({
 
 // ../dashboard/src/routes/register-agent-import-export-generation-routes.ts
 import * as fsPromises2 from "node:fs/promises";
-var mkdtemp, access5, stat7, mkdir14, rm3, fsWriteFile;
+var mkdtemp, access6, stat7, mkdir14, rm3, fsWriteFile;
 var init_register_agent_import_export_generation_routes = __esm({
   "../dashboard/src/routes/register-agent-import-export-generation-routes.ts"() {
     "use strict";
     init_api_error();
     init_ai_session_diagnostics();
     init_agent_generation();
-    ({ mkdtemp, access: access5, stat: stat7, mkdir: mkdir14, rm: rm3, writeFile: fsWriteFile } = fsPromises2);
+    ({ mkdtemp, access: access6, stat: stat7, mkdir: mkdir14, rm: rm3, writeFile: fsWriteFile } = fsPromises2);
   }
 });
 
@@ -94433,7 +94593,7 @@ var init_auth_middleware = __esm({
 
 // ../dashboard/src/server.ts
 import express from "express";
-import { join as join37, dirname as dirname10 } from "node:path";
+import { join as join37, dirname as dirname11 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 function clearAiSessionCleanupInterval() {
   if (!aiSessionCleanupIntervalHandle) {
@@ -94469,7 +94629,7 @@ var init_server = __esm({
     init_auth_middleware();
     init_remote_auth();
     init_cli_package_version();
-    __dirname = dirname10(fileURLToPath4(import.meta.url));
+    __dirname = dirname11(fileURLToPath4(import.meta.url));
     MIN_AI_SESSION_TTL_MS = 10 * 60 * 1e3;
     MAX_AI_SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1e3;
     MIN_AI_SESSION_CLEANUP_INTERVAL_MS = 60 * 1e3;
@@ -94541,7 +94701,7 @@ var init_src4 = __esm({
 });
 
 // src/project-context.ts
-import { resolve as resolve16, dirname as dirname11, basename as basename9 } from "node:path";
+import { resolve as resolve16, dirname as dirname12, basename as basename9 } from "node:path";
 async function resolveProject(projectNameFlag, cwd = process.cwd(), globalDir) {
   const central = new CentralCore(globalDir);
   await central.init();
@@ -94631,7 +94791,7 @@ async function detectProjectFromCwd(cwd, central) {
         path: currentDir
       };
     }
-    const parentDir = dirname11(currentDir);
+    const parentDir = dirname12(currentDir);
     if (parentDir === currentDir) {
       break;
     }