@hasna/loops 0.3.9 → 0.3.10

package/dist/cli/index.js

@@ -1670,6 +1670,10 @@ class Store {
     const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND status = 'running'").get(loopId);
     return (row?.count ?? 0) > 0;
   }
+  hasRunningRunForSlot(loopId, scheduledFor) {
+    const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND scheduled_for = ? AND status = 'running'").get(loopId, scheduledFor);
+    return (row?.count ?? 0) > 0;
+  }
   markRunPid(id, pid, claimedBy, opts = {}) {
     const now = (opts.now ?? new Date).toISOString();
     const res = claimedBy ? this.db.query(`UPDATE loop_runs SET pid=$pid, updated_at=$updated
@@ -3719,6 +3723,92 @@ async function runSlot(deps, loop, scheduledFor) {
   deps.onRun?.(finalRun);
   return finalRun;
 }
+function claimSlot(deps, loop, scheduledFor) {
+  const now = deps.now?.() ?? new Date;
+  deps.beforeRun?.(loop, scheduledFor);
+  if (loop.overlap === "skip" && deps.store.hasRunningRun(loop.id)) {
+    if (deps.store.hasRunningRunForSlot(loop.id, scheduledFor))
+      return;
+    let skipped;
+    try {
+      skipped = deps.store.createSkippedRun(loop, scheduledFor, "previous run still active", {
+        daemonLeaseId: deps.daemonLeaseId
+      });
+    } catch (error) {
+      if (deps.daemonLeaseId && isDaemonLeaseLost(error))
+        return;
+      throw error;
+    }
+    advanceLoop(deps.store, loop, skipped, now, true, { daemonLeaseId: deps.daemonLeaseId });
+    deps.onRun?.(skipped);
+    return skipped;
+  }
+  let claim;
+  try {
+    claim = deps.store.claimRun(loop, scheduledFor, deps.runnerId, now, { daemonLeaseId: deps.daemonLeaseId });
+  } catch (error) {
+    if (deps.daemonLeaseId && isDaemonLeaseLost(error))
+      return;
+    throw error;
+  }
+  if (!claim)
+    return;
+  deps.beforeRun?.(claim.loop, claim.run.scheduledFor);
+  deps.onRun?.(claim.run);
+  return claim;
+}
+function claimDueRuns(deps) {
+  const now = deps.now?.() ?? new Date;
+  const recovered = deps.store.recoverExpiredRunLeases(now, { daemonLeaseId: deps.daemonLeaseId });
+  const recoveredByLoop = new Map;
+  for (const run of recovered) {
+    recoveredByLoop.set(run.loopId, [...recoveredByLoop.get(run.loopId) ?? [], run]);
+  }
+  for (const runs of recoveredByLoop.values()) {
+    const loop = deps.store.getLoop(runs[0].loopId);
+    if (!loop)
+      continue;
+    const retryable = runs.filter((run) => run.attempt < loop.maxAttempts).sort((a, b) => new Date(a.scheduledFor).getTime() - new Date(b.scheduledFor).getTime())[0];
+    if (retryable) {
+      advanceLoop(deps.store, loop, retryable, new Date(retryable.finishedAt ?? now), false, {
+        daemonLeaseId: deps.daemonLeaseId
+      });
+      continue;
+    }
+    for (const run of runs) {
+      const current = deps.store.getLoop(run.loopId);
+      if (current) {
+        advanceLoop(deps.store, current, run, new Date(run.finishedAt ?? now), false, {
+          daemonLeaseId: deps.daemonLeaseId
+        });
+      }
+    }
+  }
+  const expired = deps.store.expireLoops(now, { daemonLeaseId: deps.daemonLeaseId });
+  const claims = [];
+  const claimed = [];
+  const skipped = [];
+  const maxClaims = Math.max(0, deps.maxClaims ?? Number.POSITIVE_INFINITY);
+  for (const loop of deps.store.dueLoops(now)) {
+    if (claims.length >= maxClaims)
+      break;
+    const plan = dueSlots(loop, now);
+    for (const slot of plan.slots) {
+      if (claims.length >= maxClaims)
+        break;
+      const run = claimSlot(deps, loop, slot);
+      if (!run)
+        continue;
+      if ("loop" in run) {
+        claims.push(run);
+        claimed.push(run.run);
+      } else if (run.status === "skipped") {
+        skipped.push(run);
+      }
+    }
+  }
+  return { claims, claimed, completed: [], skipped, recovered, expired };
+}
 async function tick(deps) {
   const now = deps.now?.() ?? new Date;
   const recovered = deps.store.recoverExpiredRunLeases(now, { daemonLeaseId: deps.daemonLeaseId });
@@ -3905,6 +3995,13 @@ function intervalFromEnv() {
   const value = Number(raw);
   return Number.isFinite(value) && value > 0 ? value : undefined;
 }
+function concurrencyFromEnv() {
+  const raw = process.env.LOOPS_DAEMON_CONCURRENCY;
+  if (!raw)
+    return;
+  const value = Number(raw);
+  return Number.isInteger(value) && value > 0 ? value : undefined;
+}
 async function runDaemon(opts = {}) {
   ensureDataDir();
   const pidPath = opts.pidPath ?? pidFilePath();
@@ -3919,6 +4016,7 @@ async function runDaemon(opts = {}) {
   const runnerId = `${hostname2()}:${process.pid}:${leaseId}`;
   const intervalMs = opts.intervalMs ?? intervalFromEnv() ?? 1000;
   const leaseTtlMs = opts.leaseTtlMs ?? Math.max(60000, intervalMs * 10);
+  const concurrency = Math.max(1, opts.concurrency ?? concurrencyFromEnv() ?? 4);
   const log = opts.log ?? ((message) => console.error(`[loops-daemon] ${message}`));
   const lease = store.acquireDaemonLease({
     id: leaseId,
@@ -3933,6 +4031,7 @@ async function runDaemon(opts = {}) {
   let stopFlag = false;
   let leaseLost = false;
   const runAbort = new AbortController;
+  const activeRuns = new Map;
   const requestStop = (message) => {
     stopFlag = true;
     if (!runAbort.signal.aborted)
@@ -3956,6 +4055,48 @@ async function runDaemon(opts = {}) {
   opts.signal?.addEventListener("abort", onSignal, { once: true });
   process.on("SIGINT", onSignal);
   process.on("SIGTERM", onSignal);
+  const executeDaemonRun = async (claim) => {
+    const heartbeatMs = Math.max(25, Math.min(1000, intervalMs, Math.floor(leaseTtlMs / 10)));
+    const timer = setInterval(() => {
+      try {
+        ensureLease();
+      } catch (err) {
+        log(err instanceof Error ? err.message : String(err));
+      }
+    }, heartbeatMs);
+    timer.unref();
+    try {
+      const finalRun = await executeClaimedRun({
+        store,
+        runnerId,
+        loop: claim.loop,
+        run: claim.run,
+        daemonLeaseId: leaseId,
+        beforeFinalize: () => ensureLease(),
+        execute: opts.execute ?? ((loop, run) => executeLoopTarget(store, loop, run, {
+          signal: runAbort.signal,
+          beforePersist: () => ensureLease(),
+          daemonLeaseId: leaseId,
+          onSpawn: (pid) => {
+            ensureLease();
+            store.markRunPid(run.id, pid, runnerId, { daemonLeaseId: leaseId });
+          }
+        })),
+        onError: (loop, err) => log(`loop ${loop.id} failed: ${err instanceof Error ? err.message : String(err)}`)
+      });
+      ensureLease();
+      if (leaseLost)
+        throw new Error("daemon lease lost during run");
+      advanceLoop(store, claim.loop, finalRun, new Date(finalRun.finishedAt ?? new Date), finalRun.status === "succeeded", { daemonLeaseId: leaseId });
+      log(`run ${finalRun.id} ${finalRun.status} loop=${claim.loop.id}`);
+    } finally {
+      clearInterval(timer);
+    }
+  };
+  const startClaim = (claim) => {
+    const task = executeDaemonRun(claim).catch((err) => log(`run ${claim.run.id} error: ${err instanceof Error ? err.message : String(err)}`)).finally(() => activeRuns.delete(claim.run.id));
+    activeRuns.set(claim.run.id, task);
+  };
   try {
     await runLoop({
       intervalMs,
@@ -3964,49 +4105,26 @@ async function runDaemon(opts = {}) {
       onTickError: (err) => log(`tick error: ${err instanceof Error ? err.message : String(err)}`),
       tickFn: async () => {
         ensureLease();
-        const result = await tick({
+        const available = Math.max(0, concurrency - activeRuns.size);
+        const result = claimDueRuns({
           store,
           runnerId,
           daemonLeaseId: leaseId,
           beforeRun: () => ensureLease(),
-          execute: async (loop, run) => {
-            const heartbeatMs = Math.max(25, Math.min(1000, intervalMs, Math.floor(leaseTtlMs / 10)));
-            const timer = setInterval(() => {
-              try {
-                ensureLease();
-              } catch (err) {
-                log(err instanceof Error ? err.message : String(err));
-              }
-            }, heartbeatMs);
-            timer.unref();
-            try {
-              const result2 = await executeLoopTarget(store, loop, run, {
-                signal: runAbort.signal,
-                beforePersist: () => ensureLease(),
-                daemonLeaseId: leaseId,
-                onSpawn: (pid) => {
-                  ensureLease();
-                  store.markRunPid(run.id, pid, runnerId, { daemonLeaseId: leaseId });
-                }
-              });
-              ensureLease();
-              if (leaseLost)
-                throw new Error("daemon lease lost during run");
-              return result2;
-            } finally {
-              clearInterval(timer);
-            }
-          },
-          beforeFinalize: () => ensureLease(),
-          onError: (loop, err) => log(`loop ${loop.id} failed: ${err instanceof Error ? err.message : String(err)}`)
+          maxClaims: available
         });
-        const changed = result.completed.length + result.skipped.length + result.recovered.length + result.expired.length;
+        for (const claim of result.claims)
+          startClaim(claim);
+        const changed = result.claims.length + result.skipped.length + result.recovered.length + result.expired.length;
         if (changed > 0) {
-          log(`tick completed=${result.completed.length} skipped=${result.skipped.length} recovered=${result.recovered.length} expired=${result.expired.length}`);
+          log(`tick claimed=${result.claims.length} active=${activeRuns.size} skipped=${result.skipped.length} recovered=${result.recovered.length} expired=${result.expired.length}`);
         }
       }
     });
   } finally {
+    if (activeRuns.size > 0 && !runAbort.signal.aborted)
+      runAbort.abort();
+    await Promise.allSettled([...activeRuns.values()]);
     opts.signal?.removeEventListener("abort", onSignal);
     process.off("SIGINT", onSignal);
     process.off("SIGTERM", onSignal);
@@ -4220,7 +4338,7 @@ function runDoctor(store) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.9",
+  version: "0.3.10",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",

package/dist/daemon/daemon.d.ts

@@ -1,9 +1,12 @@
 import { Store } from "../lib/store.js";
+import type { ExecutorResult, Loop, LoopRun } from "../types.js";
 export interface RunDaemonOptions {
     intervalMs?: number;
     leaseTtlMs?: number;
+    concurrency?: number;
     store?: Store;
     pidPath?: string;
+    execute?: (loop: Loop, run: LoopRun) => Promise<ExecutorResult>;
     shouldStop?: () => boolean;
     sleep?: (ms: number) => Promise<void>;
     log?: (message: string) => void;

package/dist/daemon/index.js

@@ -1670,6 +1670,10 @@ class Store {
     const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND status = 'running'").get(loopId);
     return (row?.count ?? 0) > 0;
   }
+  hasRunningRunForSlot(loopId, scheduledFor) {
+    const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND scheduled_for = ? AND status = 'running'").get(loopId, scheduledFor);
+    return (row?.count ?? 0) > 0;
+  }
   markRunPid(id, pid, claimedBy, opts = {}) {
     const now = (opts.now ?? new Date).toISOString();
     const res = claimedBy ? this.db.query(`UPDATE loop_runs SET pid=$pid, updated_at=$updated
@@ -3614,6 +3618,92 @@ async function runSlot(deps, loop, scheduledFor) {
   deps.onRun?.(finalRun);
   return finalRun;
 }
+function claimSlot(deps, loop, scheduledFor) {
+  const now = deps.now?.() ?? new Date;
+  deps.beforeRun?.(loop, scheduledFor);
+  if (loop.overlap === "skip" && deps.store.hasRunningRun(loop.id)) {
+    if (deps.store.hasRunningRunForSlot(loop.id, scheduledFor))
+      return;
+    let skipped;
+    try {
+      skipped = deps.store.createSkippedRun(loop, scheduledFor, "previous run still active", {
+        daemonLeaseId: deps.daemonLeaseId
+      });
+    } catch (error) {
+      if (deps.daemonLeaseId && isDaemonLeaseLost(error))
+        return;
+      throw error;
+    }
+    advanceLoop(deps.store, loop, skipped, now, true, { daemonLeaseId: deps.daemonLeaseId });
+    deps.onRun?.(skipped);
+    return skipped;
+  }
+  let claim;
+  try {
+    claim = deps.store.claimRun(loop, scheduledFor, deps.runnerId, now, { daemonLeaseId: deps.daemonLeaseId });
+  } catch (error) {
+    if (deps.daemonLeaseId && isDaemonLeaseLost(error))
+      return;
+    throw error;
+  }
+  if (!claim)
+    return;
+  deps.beforeRun?.(claim.loop, claim.run.scheduledFor);
+  deps.onRun?.(claim.run);
+  return claim;
+}
+function claimDueRuns(deps) {
+  const now = deps.now?.() ?? new Date;
+  const recovered = deps.store.recoverExpiredRunLeases(now, { daemonLeaseId: deps.daemonLeaseId });
+  const recoveredByLoop = new Map;
+  for (const run of recovered) {
+    recoveredByLoop.set(run.loopId, [...recoveredByLoop.get(run.loopId) ?? [], run]);
+  }
+  for (const runs of recoveredByLoop.values()) {
+    const loop = deps.store.getLoop(runs[0].loopId);
+    if (!loop)
+      continue;
+    const retryable = runs.filter((run) => run.attempt < loop.maxAttempts).sort((a, b) => new Date(a.scheduledFor).getTime() - new Date(b.scheduledFor).getTime())[0];
+    if (retryable) {
+      advanceLoop(deps.store, loop, retryable, new Date(retryable.finishedAt ?? now), false, {
+        daemonLeaseId: deps.daemonLeaseId
+      });
+      continue;
+    }
+    for (const run of runs) {
+      const current = deps.store.getLoop(run.loopId);
+      if (current) {
+        advanceLoop(deps.store, current, run, new Date(run.finishedAt ?? now), false, {
+          daemonLeaseId: deps.daemonLeaseId
+        });
+      }
+    }
+  }
+  const expired = deps.store.expireLoops(now, { daemonLeaseId: deps.daemonLeaseId });
+  const claims = [];
+  const claimed = [];
+  const skipped = [];
+  const maxClaims = Math.max(0, deps.maxClaims ?? Number.POSITIVE_INFINITY);
+  for (const loop of deps.store.dueLoops(now)) {
+    if (claims.length >= maxClaims)
+      break;
+    const plan = dueSlots(loop, now);
+    for (const slot of plan.slots) {
+      if (claims.length >= maxClaims)
+        break;
+      const run = claimSlot(deps, loop, slot);
+      if (!run)
+        continue;
+      if ("loop" in run) {
+        claims.push(run);
+        claimed.push(run.run);
+      } else if (run.status === "skipped") {
+        skipped.push(run);
+      }
+    }
+  }
+  return { claims, claimed, completed: [], skipped, recovered, expired };
+}
 async function tick(deps) {
   const now = deps.now?.() ?? new Date;
   const recovered = deps.store.recoverExpiredRunLeases(now, { daemonLeaseId: deps.daemonLeaseId });
@@ -3797,6 +3887,13 @@ function intervalFromEnv() {
   const value = Number(raw);
   return Number.isFinite(value) && value > 0 ? value : undefined;
 }
+function concurrencyFromEnv() {
+  const raw = process.env.LOOPS_DAEMON_CONCURRENCY;
+  if (!raw)
+    return;
+  const value = Number(raw);
+  return Number.isInteger(value) && value > 0 ? value : undefined;
+}
 async function runDaemon(opts = {}) {
   ensureDataDir();
   const pidPath = opts.pidPath ?? pidFilePath();
@@ -3811,6 +3908,7 @@ async function runDaemon(opts = {}) {
   const runnerId = `${hostname2()}:${process.pid}:${leaseId}`;
   const intervalMs = opts.intervalMs ?? intervalFromEnv() ?? 1000;
   const leaseTtlMs = opts.leaseTtlMs ?? Math.max(60000, intervalMs * 10);
+  const concurrency = Math.max(1, opts.concurrency ?? concurrencyFromEnv() ?? 4);
   const log = opts.log ?? ((message) => console.error(`[loops-daemon] ${message}`));
   const lease = store.acquireDaemonLease({
     id: leaseId,
@@ -3825,6 +3923,7 @@ async function runDaemon(opts = {}) {
   let stopFlag = false;
   let leaseLost = false;
   const runAbort = new AbortController;
+  const activeRuns = new Map;
   const requestStop = (message) => {
     stopFlag = true;
     if (!runAbort.signal.aborted)
@@ -3848,6 +3947,48 @@ async function runDaemon(opts = {}) {
   opts.signal?.addEventListener("abort", onSignal, { once: true });
   process.on("SIGINT", onSignal);
   process.on("SIGTERM", onSignal);
+  const executeDaemonRun = async (claim) => {
+    const heartbeatMs = Math.max(25, Math.min(1000, intervalMs, Math.floor(leaseTtlMs / 10)));
+    const timer = setInterval(() => {
+      try {
+        ensureLease();
+      } catch (err) {
+        log(err instanceof Error ? err.message : String(err));
+      }
+    }, heartbeatMs);
+    timer.unref();
+    try {
+      const finalRun = await executeClaimedRun({
+        store,
+        runnerId,
+        loop: claim.loop,
+        run: claim.run,
+        daemonLeaseId: leaseId,
+        beforeFinalize: () => ensureLease(),
+        execute: opts.execute ?? ((loop, run) => executeLoopTarget(store, loop, run, {
+          signal: runAbort.signal,
+          beforePersist: () => ensureLease(),
+          daemonLeaseId: leaseId,
+          onSpawn: (pid) => {
+            ensureLease();
+            store.markRunPid(run.id, pid, runnerId, { daemonLeaseId: leaseId });
+          }
+        })),
+        onError: (loop, err) => log(`loop ${loop.id} failed: ${err instanceof Error ? err.message : String(err)}`)
+      });
+      ensureLease();
+      if (leaseLost)
+        throw new Error("daemon lease lost during run");
+      advanceLoop(store, claim.loop, finalRun, new Date(finalRun.finishedAt ?? new Date), finalRun.status === "succeeded", { daemonLeaseId: leaseId });
+      log(`run ${finalRun.id} ${finalRun.status} loop=${claim.loop.id}`);
+    } finally {
+      clearInterval(timer);
+    }
+  };
+  const startClaim = (claim) => {
+    const task = executeDaemonRun(claim).catch((err) => log(`run ${claim.run.id} error: ${err instanceof Error ? err.message : String(err)}`)).finally(() => activeRuns.delete(claim.run.id));
+    activeRuns.set(claim.run.id, task);
+  };
   try {
     await runLoop({
       intervalMs,
@@ -3856,49 +3997,26 @@ async function runDaemon(opts = {}) {
       onTickError: (err) => log(`tick error: ${err instanceof Error ? err.message : String(err)}`),
       tickFn: async () => {
         ensureLease();
-        const result = await tick({
+        const available = Math.max(0, concurrency - activeRuns.size);
+        const result = claimDueRuns({
           store,
           runnerId,
           daemonLeaseId: leaseId,
           beforeRun: () => ensureLease(),
-          execute: async (loop, run) => {
-            const heartbeatMs = Math.max(25, Math.min(1000, intervalMs, Math.floor(leaseTtlMs / 10)));
-            const timer = setInterval(() => {
-              try {
-                ensureLease();
-              } catch (err) {
-                log(err instanceof Error ? err.message : String(err));
-              }
-            }, heartbeatMs);
-            timer.unref();
-            try {
-              const result2 = await executeLoopTarget(store, loop, run, {
-                signal: runAbort.signal,
-                beforePersist: () => ensureLease(),
-                daemonLeaseId: leaseId,
-                onSpawn: (pid) => {
-                  ensureLease();
-                  store.markRunPid(run.id, pid, runnerId, { daemonLeaseId: leaseId });
-                }
-              });
-              ensureLease();
-              if (leaseLost)
-                throw new Error("daemon lease lost during run");
-              return result2;
-            } finally {
-              clearInterval(timer);
-            }
-          },
-          beforeFinalize: () => ensureLease(),
-          onError: (loop, err) => log(`loop ${loop.id} failed: ${err instanceof Error ? err.message : String(err)}`)
+          maxClaims: available
         });
-        const changed = result.completed.length + result.skipped.length + result.recovered.length + result.expired.length;
+        for (const claim of result.claims)
+          startClaim(claim);
+        const changed = result.claims.length + result.skipped.length + result.recovered.length + result.expired.length;
         if (changed > 0) {
-          log(`tick completed=${result.completed.length} skipped=${result.skipped.length} recovered=${result.recovered.length} expired=${result.expired.length}`);
+          log(`tick claimed=${result.claims.length} active=${activeRuns.size} skipped=${result.skipped.length} recovered=${result.recovered.length} expired=${result.expired.length}`);
         }
       }
     });
   } finally {
+    if (activeRuns.size > 0 && !runAbort.signal.aborted)
+      runAbort.abort();
+    await Promise.allSettled([...activeRuns.values()]);
     opts.signal?.removeEventListener("abort", onSignal);
     process.off("SIGINT", onSignal);
     process.off("SIGTERM", onSignal);
@@ -4020,7 +4138,7 @@ function enableStartup(result) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.9",
+  version: "0.3.10",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -4110,7 +4228,7 @@ function packageVersion() {
 // src/daemon/index.ts
 var program = new Command;
 program.name("loops-daemon").description("OpenLoops daemon helper").version(packageVersion());
-program.command("run").option("--interval-ms <ms>", "tick interval", (value) => Number(value)).action(async (opts) => runDaemon({ intervalMs: opts.intervalMs }));
+program.command("run").option("--interval-ms <ms>", "tick interval", (value) => Number(value)).option("--concurrency <n>", "maximum loop runs to execute concurrently", (value) => Number(value)).action(async (opts) => runDaemon({ intervalMs: opts.intervalMs, concurrency: opts.concurrency }));
 program.command("start").action(async () => {
   const result = await startDaemon({ cliEntry: process.argv[1] ?? "loops-daemon", args: ["run"] });
   console.log(JSON.stringify(result, null, 2));

package/dist/index.js

@@ -1668,6 +1668,10 @@ class Store {
     const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND status = 'running'").get(loopId);
     return (row?.count ?? 0) > 0;
   }
+  hasRunningRunForSlot(loopId, scheduledFor) {
+    const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND scheduled_for = ? AND status = 'running'").get(loopId, scheduledFor);
+    return (row?.count ?? 0) > 0;
+  }
   markRunPid(id, pid, claimedBy, opts = {}) {
     const now = (opts.now ?? new Date).toISOString();
     const res = claimedBy ? this.db.query(`UPDATE loop_runs SET pid=$pid, updated_at=$updated
@@ -3604,6 +3608,92 @@ async function runSlot(deps, loop, scheduledFor) {
   deps.onRun?.(finalRun);
   return finalRun;
 }
+function claimSlot(deps, loop, scheduledFor) {
+  const now = deps.now?.() ?? new Date;
+  deps.beforeRun?.(loop, scheduledFor);
+  if (loop.overlap === "skip" && deps.store.hasRunningRun(loop.id)) {
+    if (deps.store.hasRunningRunForSlot(loop.id, scheduledFor))
+      return;
+    let skipped;
+    try {
+      skipped = deps.store.createSkippedRun(loop, scheduledFor, "previous run still active", {
+        daemonLeaseId: deps.daemonLeaseId
+      });
+    } catch (error) {
+      if (deps.daemonLeaseId && isDaemonLeaseLost(error))
+        return;
+      throw error;
+    }
+    advanceLoop(deps.store, loop, skipped, now, true, { daemonLeaseId: deps.daemonLeaseId });
+    deps.onRun?.(skipped);
+    return skipped;
+  }
+  let claim;
+  try {
+    claim = deps.store.claimRun(loop, scheduledFor, deps.runnerId, now, { daemonLeaseId: deps.daemonLeaseId });
+  } catch (error) {
+    if (deps.daemonLeaseId && isDaemonLeaseLost(error))
+      return;
+    throw error;
+  }
+  if (!claim)
+    return;
+  deps.beforeRun?.(claim.loop, claim.run.scheduledFor);
+  deps.onRun?.(claim.run);
+  return claim;
+}
+function claimDueRuns(deps) {
+  const now = deps.now?.() ?? new Date;
+  const recovered = deps.store.recoverExpiredRunLeases(now, { daemonLeaseId: deps.daemonLeaseId });
+  const recoveredByLoop = new Map;
+  for (const run of recovered) {
+    recoveredByLoop.set(run.loopId, [...recoveredByLoop.get(run.loopId) ?? [], run]);
+  }
+  for (const runs of recoveredByLoop.values()) {
+    const loop = deps.store.getLoop(runs[0].loopId);
+    if (!loop)
+      continue;
+    const retryable = runs.filter((run) => run.attempt < loop.maxAttempts).sort((a, b) => new Date(a.scheduledFor).getTime() - new Date(b.scheduledFor).getTime())[0];
+    if (retryable) {
+      advanceLoop(deps.store, loop, retryable, new Date(retryable.finishedAt ?? now), false, {
+        daemonLeaseId: deps.daemonLeaseId
+      });
+      continue;
+    }
+    for (const run of runs) {
+      const current = deps.store.getLoop(run.loopId);
+      if (current) {
+        advanceLoop(deps.store, current, run, new Date(run.finishedAt ?? now), false, {
+          daemonLeaseId: deps.daemonLeaseId
+        });
+      }
+    }
+  }
+  const expired = deps.store.expireLoops(now, { daemonLeaseId: deps.daemonLeaseId });
+  const claims = [];
+  const claimed = [];
+  const skipped = [];
+  const maxClaims = Math.max(0, deps.maxClaims ?? Number.POSITIVE_INFINITY);
+  for (const loop of deps.store.dueLoops(now)) {
+    if (claims.length >= maxClaims)
+      break;
+    const plan = dueSlots(loop, now);
+    for (const slot of plan.slots) {
+      if (claims.length >= maxClaims)
+        break;
+      const run = claimSlot(deps, loop, slot);
+      if (!run)
+        continue;
+      if ("loop" in run) {
+        claims.push(run);
+        claimed.push(run.run);
+      } else if (run.status === "skipped") {
+        skipped.push(run);
+      }
+    }
+  }
+  return { claims, claimed, completed: [], skipped, recovered, expired };
+}
 async function tick(deps) {
   const now = deps.now?.() ?? new Date;
   const recovered = deps.store.recoverExpiredRunLeases(now, { daemonLeaseId: deps.daemonLeaseId });

package/dist/lib/scheduler.d.ts

@@ -18,6 +18,13 @@ export interface TickResult {
     recovered: LoopRun[];
     expired: Loop[];
 }
+export interface ClaimedLoopRun {
+    loop: Loop;
+    run: LoopRun;
+}
+export interface ClaimDueRunsResult extends TickResult {
+    claims: ClaimedLoopRun[];
+}
 export declare function manualRunScheduledFor(loop: Loop, now?: Date): string;
 export declare function shouldAdvanceManualRun(loop: Loop, scheduledFor: string, now?: Date): boolean;
 export type ManualRunSource = "ad_hoc" | "due_slot" | "retry_slot";
@@ -36,4 +43,7 @@ export declare function executeClaimedRun(deps: {
     execute?: (loop: Loop, run: LoopRun) => Promise<ExecutorResult>;
     onError?: (loop: Loop, error: unknown) => void;
 }): Promise<LoopRun>;
+export declare function claimDueRuns(deps: SchedulerDeps & {
+    maxClaims?: number;
+}): ClaimDueRunsResult;
 export declare function tick(deps: SchedulerDeps): Promise<TickResult>;

package/dist/lib/store.d.ts

@@ -130,6 +130,7 @@ export declare class Store {
     appendWorkflowEvent(workflowRunId: string, eventType: string, stepId?: string, payload?: Record<string, unknown>): WorkflowEvent;
     listWorkflowEvents(workflowRunId: string, limit?: number): WorkflowEvent[];
     hasRunningRun(loopId: string): boolean;
+    hasRunningRunForSlot(loopId: string, scheduledFor: string): boolean;
     markRunPid(id: string, pid: number, claimedBy?: string, opts?: DaemonLeaseFence): LoopRun | undefined;
     private hasLiveWorkflowStepProcesses;
     createSkippedRun(loop: Loop, scheduledFor: string, reason: string, opts?: DaemonLeaseFence): LoopRun;

package/dist/lib/store.js

@@ -1668,6 +1668,10 @@ class Store {
     const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND status = 'running'").get(loopId);
     return (row?.count ?? 0) > 0;
   }
+  hasRunningRunForSlot(loopId, scheduledFor) {
+    const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND scheduled_for = ? AND status = 'running'").get(loopId, scheduledFor);
+    return (row?.count ?? 0) > 0;
+  }
   markRunPid(id, pid, claimedBy, opts = {}) {
     const now = (opts.now ?? new Date).toISOString();
     const res = claimedBy ? this.db.query(`UPDATE loop_runs SET pid=$pid, updated_at=$updated

package/dist/sdk/index.js

@@ -1668,6 +1668,10 @@ class Store {
     const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND status = 'running'").get(loopId);
     return (row?.count ?? 0) > 0;
   }
+  hasRunningRunForSlot(loopId, scheduledFor) {
+    const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND scheduled_for = ? AND status = 'running'").get(loopId, scheduledFor);
+    return (row?.count ?? 0) > 0;
+  }
   markRunPid(id, pid, claimedBy, opts = {}) {
     const now = (opts.now ?? new Date).toISOString();
     const res = claimedBy ? this.db.query(`UPDATE loop_runs SET pid=$pid, updated_at=$updated
@@ -3604,6 +3608,92 @@ async function runSlot(deps, loop, scheduledFor) {
   deps.onRun?.(finalRun);
   return finalRun;
 }
+function claimSlot(deps, loop, scheduledFor) {
+  const now = deps.now?.() ?? new Date;
+  deps.beforeRun?.(loop, scheduledFor);
+  if (loop.overlap === "skip" && deps.store.hasRunningRun(loop.id)) {
+    if (deps.store.hasRunningRunForSlot(loop.id, scheduledFor))
+      return;
+    let skipped;
+    try {
+      skipped = deps.store.createSkippedRun(loop, scheduledFor, "previous run still active", {
+        daemonLeaseId: deps.daemonLeaseId
+      });
+    } catch (error) {
+      if (deps.daemonLeaseId && isDaemonLeaseLost(error))
+        return;
+      throw error;
+    }
+    advanceLoop(deps.store, loop, skipped, now, true, { daemonLeaseId: deps.daemonLeaseId });
+    deps.onRun?.(skipped);
+    return skipped;
+  }
+  let claim;
+  try {
+    claim = deps.store.claimRun(loop, scheduledFor, deps.runnerId, now, { daemonLeaseId: deps.daemonLeaseId });
+  } catch (error) {
+    if (deps.daemonLeaseId && isDaemonLeaseLost(error))
+      return;
+    throw error;
+  }
+  if (!claim)
+    return;
+  deps.beforeRun?.(claim.loop, claim.run.scheduledFor);
+  deps.onRun?.(claim.run);
+  return claim;
+}
+function claimDueRuns(deps) {
+  const now = deps.now?.() ?? new Date;
+  const recovered = deps.store.recoverExpiredRunLeases(now, { daemonLeaseId: deps.daemonLeaseId });
+  const recoveredByLoop = new Map;
+  for (const run of recovered) {
+    recoveredByLoop.set(run.loopId, [...recoveredByLoop.get(run.loopId) ?? [], run]);
+  }
+  for (const runs of recoveredByLoop.values()) {
+    const loop = deps.store.getLoop(runs[0].loopId);
+    if (!loop)
+      continue;
+    const retryable = runs.filter((run) => run.attempt < loop.maxAttempts).sort((a, b) => new Date(a.scheduledFor).getTime() - new Date(b.scheduledFor).getTime())[0];
+    if (retryable) {
+      advanceLoop(deps.store, loop, retryable, new Date(retryable.finishedAt ?? now), false, {
+        daemonLeaseId: deps.daemonLeaseId
+      });
+      continue;
+    }
+    for (const run of runs) {
+      const current = deps.store.getLoop(run.loopId);
+      if (current) {
+        advanceLoop(deps.store, current, run, new Date(run.finishedAt ?? now), false, {
+          daemonLeaseId: deps.daemonLeaseId
+        });
+      }
+    }
+  }
+  const expired = deps.store.expireLoops(now, { daemonLeaseId: deps.daemonLeaseId });
+  const claims = [];
+  const claimed = [];
+  const skipped = [];
+  const maxClaims = Math.max(0, deps.maxClaims ?? Number.POSITIVE_INFINITY);
+  for (const loop of deps.store.dueLoops(now)) {
+    if (claims.length >= maxClaims)
+      break;
+    const plan = dueSlots(loop, now);
+    for (const slot of plan.slots) {
+      if (claims.length >= maxClaims)
+        break;
+      const run = claimSlot(deps, loop, slot);
+      if (!run)
+        continue;
+      if ("loop" in run) {
+        claims.push(run);
+        claimed.push(run.run);
+      } else if (run.status === "skipped") {
+        skipped.push(run);
+      }
+    }
+  }
+  return { claims, claimed, completed: [], skipped, recovered, expired };
+}
 async function tick(deps) {
   const now = deps.now?.() ?? new Date;
   const recovered = deps.store.recoverExpiredRunLeases(now, { daemonLeaseId: deps.daemonLeaseId });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",