@hasna/loops 0.3.23 → 0.3.24

package/dist/cli/index.js

@@ -3243,6 +3243,28 @@ async function executeLoop(loop, run, opts = {}) {
   if (loop.target.type === "workflow") {
     throw new Error("workflow loop targets must be executed with executeLoopTarget");
   }
+  if (loop.target.preflight?.beforeRun) {
+    const startedAt = nowIso();
+    try {
+      preflightTarget(loop.target, {
+        loopId: loop.id,
+        loopName: loop.name,
+        runId: run.id,
+        scheduledFor: run.scheduledFor
+      }, { ...opts, machine: opts.machine ?? loop.machine });
+    } catch (error) {
+      const finishedAt = nowIso();
+      return {
+        status: "failed",
+        stdout: "",
+        stderr: "",
+        error: `runtime preflight failed: ${error instanceof Error ? error.message : String(error)}`,
+        startedAt,
+        finishedAt,
+        durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+      };
+    }
+  }
   return executeTarget(loop.target, {
     loopId: loop.id,
     loopName: loop.name,
@@ -3824,8 +3846,33 @@ function preflightWorkflow(workflow, opts = {}) {
     }
   });
 }
+function preflightFailureResult(error, startedAt = nowIso()) {
+  const finishedAt = nowIso();
+  return {
+    status: "failed",
+    stdout: "",
+    stderr: "",
+    error: `runtime preflight failed: ${error instanceof Error ? error.message : String(error)}`,
+    startedAt,
+    finishedAt,
+    durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+  };
+}
 async function executeLoopTarget(store, loop, run, opts = {}) {
   if (loop.target.type !== "workflow") {
+    if (loop.goal && loop.target.preflight?.beforeRun) {
+      const startedAt = nowIso();
+      try {
+        preflightTarget(loop.target, {
+          loopId: loop.id,
+          loopName: loop.name,
+          runId: run.id,
+          scheduledFor: run.scheduledFor
+        }, { ...opts, machine: opts.machine ?? loop.machine });
+      } catch (error) {
+        return preflightFailureResult(error, startedAt);
+      }
+    }
     if (loop.goal) {
       return runGoal(store, loop.goal, {
         ...opts,
@@ -3841,6 +3888,14 @@ async function executeLoopTarget(store, loop, run, opts = {}) {
     return executeLoop(loop, run, opts);
   }
   const workflow = store.requireWorkflow(loop.target.workflowId);
+  if (loop.target.preflight?.beforeRun) {
+    const startedAt = nowIso();
+    try {
+      preflightWorkflow(workflow, { ...opts, machine: opts.machine ?? loop.machine });
+    } catch (error) {
+      return preflightFailureResult(error, startedAt);
+    }
+  }
   if (loop.goal) {
     return runGoal(store, loop.goal, {
       ...opts,
@@ -4701,6 +4756,7 @@ var CLASSIFICATIONS = [
   "context_length",
   "schema_response_format",
   "node_init",
+  "preflight",
   "timeout",
   "sigsegv",
   "skipped_previous_active",
@@ -4748,6 +4804,8 @@ function classifyRunFailure(run) {
     classification = "timeout";
   else if (run.status === "skipped" && /previous run still active/.test(text))
     classification = "skipped_previous_active";
+  else if (/runtime preflight failed|preflight failed|executable not found in path|none of required executables found|auth profile preflight failed|profile not found/.test(text))
+    classification = "preflight";
   else if (/rate limit|too many requests|429\b|quota exceeded/.test(text))
     classification = "rate_limit";
   else if (/unauthorized|authentication|auth\b|api key|invalid token|permission denied|401\b|403\b/.test(text))
@@ -5143,7 +5201,7 @@ function buildScriptInventoryReport(store, opts = {}) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.23",
+  version: "0.3.24",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -5803,6 +5861,9 @@ function accountPoolFromOpts(opts) {
 function roleAccountFromOpts(opts, profile) {
   return profile ? { profile, tool: opts.accountTool } : undefined;
 }
+function runtimePreflightFromOpts(opts) {
+  return opts.preflightEachRun ? { beforeRun: true } : undefined;
+}
 function parseVars(values) {
   const vars = {};
   for (const value of values ?? []) {
@@ -6120,7 +6181,7 @@ function permissionModeFromOpts(opts, provider) {
   return mode;
 }
 var create = program.command("create").description("create loops");
-addGoalOptions(addAccountOptions(addMachineOptions(addScheduleOptions(create.command("command <name>").description("create a deterministic shell command loop").requiredOption("--cmd <command>", "command string to execute").option("--cwd <dir>", "working directory").option("--timeout <duration>", "run timeout").option("--no-shell", "execute without a shell").option("--preflight", "check target executables/accounts before storing the loop"))))).action((name, opts) => {
+addGoalOptions(addAccountOptions(addMachineOptions(addScheduleOptions(create.command("command <name>").description("create a deterministic shell command loop").requiredOption("--cmd <command>", "command string to execute").option("--cwd <dir>", "working directory").option("--timeout <duration>", "run timeout").option("--no-shell", "execute without a shell").option("--preflight-each-run", "check target executables/accounts before every scheduled run").option("--preflight", "check target executables/accounts before storing the loop"))))).action((name, opts) => {
   const store = new Store;
   try {
     const target = {
@@ -6129,7 +6190,8 @@ addGoalOptions(addAccountOptions(addMachineOptions(addScheduleOptions(create.com
       cwd: opts.cwd,
       shell: opts.shell,
       timeoutMs: opts.timeout ? parseDuration(opts.timeout) : undefined,
-      account: accountFromOpts(opts)
+      account: accountFromOpts(opts),
+      preflight: runtimePreflightFromOpts(opts)
     };
     const input = baseCreateInput(name, opts, target);
     const preflight = opts.preflight ? preflightLoopTarget(input.target, { name, type: "command" }, { loopName: name }, { machine: input.machine }) : undefined;
@@ -6139,7 +6201,7 @@ addGoalOptions(addAccountOptions(addMachineOptions(addScheduleOptions(create.com
     store.close();
   }
 });
-addGoalOptions(addAccountOptions(addMachineOptions(addScheduleOptions(create.command("agent <name>").description("create a headless coding-agent loop").requiredOption("--provider <provider>", "claude, cursor, codewith, aicopilot, opencode, or codex").requiredOption("--prompt <prompt>", "agent prompt").option("--cwd <dir>", "working directory").option("--model <model>", "model").option("--variant <variant>", "provider-specific model variant or reasoning effort").option("--agent <agent>", "provider-specific agent").option("--auth-profile <profile>", "provider-native auth profile; currently supported for codewith").option("--timeout <duration>", "run timeout").option("--permission-mode <mode>", "provider permission mode: default, plan, auto, or bypass").option("--sandbox <mode>", "provider sandbox: codewith/codex use read-only/workspace-write/danger-full-access; cursor uses enabled/disabled").option("--allow-tool <name>", "advisory per-session tool allowlist metadata; may be repeated or comma-separated", collectValues, []).option("--allow-command <name>", "advisory per-session command allowlist metadata; may be repeated or comma-separated", collectValues, []).option("--config-isolation <mode>", "safe or none", "safe").option("--preflight", "check target executables/accounts before storing the loop"))))).action((name, opts) => {
+addGoalOptions(addAccountOptions(addMachineOptions(addScheduleOptions(create.command("agent <name>").description("create a headless coding-agent loop").requiredOption("--provider <provider>", "claude, cursor, codewith, aicopilot, opencode, or codex").requiredOption("--prompt <prompt>", "agent prompt").option("--cwd <dir>", "working directory").option("--model <model>", "model").option("--variant <variant>", "provider-specific model variant or reasoning effort").option("--agent <agent>", "provider-specific agent").option("--auth-profile <profile>", "provider-native auth profile; currently supported for codewith").option("--timeout <duration>", "run timeout").option("--permission-mode <mode>", "provider permission mode: default, plan, auto, or bypass").option("--sandbox <mode>", "provider sandbox: codewith/codex use read-only/workspace-write/danger-full-access; cursor uses enabled/disabled").option("--allow-tool <name>", "advisory per-session tool allowlist metadata; may be repeated or comma-separated", collectValues, []).option("--allow-command <name>", "advisory per-session command allowlist metadata; may be repeated or comma-separated", collectValues, []).option("--config-isolation <mode>", "safe or none", "safe").option("--preflight-each-run", "check provider/account readiness before every scheduled run").option("--preflight", "check target executables/accounts before storing the loop"))))).action((name, opts) => {
   const provider = opts.provider;
   if (!["claude", "cursor", "codewith", "aicopilot", "opencode", "codex"].includes(provider)) {
     throw new Error("unsupported provider");
@@ -6163,7 +6225,8 @@ addGoalOptions(addAccountOptions(addMachineOptions(addScheduleOptions(create.com
       permissionMode: permissionModeFromOpts(opts, provider),
       sandbox: sandboxFromOpts(opts, provider),
       allowlist: allowlistFromOpts(opts),
-      account: accountFromOpts(opts)
+      account: accountFromOpts(opts),
+      preflight: runtimePreflightFromOpts(opts)
     };
     const input = baseCreateInput(name, opts, target);
     const preflight = opts.preflight ? preflightLoopTarget(input.target, { name, type: "agent", provider }, { loopName: name }, { machine: input.machine }) : undefined;
@@ -6173,13 +6236,14 @@ addGoalOptions(addAccountOptions(addMachineOptions(addScheduleOptions(create.com
     store.close();
   }
 });
-addGoalOptions(addMachineOptions(addScheduleOptions(create.command("workflow <name>").description("schedule a stored workflow").requiredOption("--workflow <idOrName>", "workflow id or name").option("--preflight", "check workflow step executables/accounts before storing the loop")))).action((name, opts) => {
+addGoalOptions(addMachineOptions(addScheduleOptions(create.command("workflow <name>").description("schedule a stored workflow").requiredOption("--workflow <idOrName>", "workflow id or name").option("--preflight-each-run", "check workflow steps before every scheduled run").option("--preflight", "check workflow step executables/accounts before storing the loop")))).action((name, opts) => {
   const store = new Store;
   try {
     const workflow = store.requireWorkflow(opts.workflow);
     const target = {
       type: "workflow",
-      workflowId: workflow.id
+      workflowId: workflow.id,
+      preflight: runtimePreflightFromOpts(opts)
     };
     const input = baseCreateInput(name, opts, target);
     const preflight = opts.preflight ? preflightStoredWorkflow(workflow, { name, type: "workflow", workflow: workflow.name }, { machine: input.machine }) : undefined;

package/dist/daemon/index.js

@@ -3134,6 +3134,28 @@ async function executeLoop(loop, run, opts = {}) {
   if (loop.target.type === "workflow") {
     throw new Error("workflow loop targets must be executed with executeLoopTarget");
   }
+  if (loop.target.preflight?.beforeRun) {
+    const startedAt = nowIso();
+    try {
+      preflightTarget(loop.target, {
+        loopId: loop.id,
+        loopName: loop.name,
+        runId: run.id,
+        scheduledFor: run.scheduledFor
+      }, { ...opts, machine: opts.machine ?? loop.machine });
+    } catch (error) {
+      const finishedAt = nowIso();
+      return {
+        status: "failed",
+        stdout: "",
+        stderr: "",
+        error: `runtime preflight failed: ${error instanceof Error ? error.message : String(error)}`,
+        startedAt,
+        finishedAt,
+        durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+      };
+    }
+  }
   return executeTarget(loop.target, {
     loopId: loop.id,
     loopName: loop.name,
@@ -3715,8 +3737,33 @@ function preflightWorkflow(workflow, opts = {}) {
     }
   });
 }
+function preflightFailureResult(error, startedAt = nowIso()) {
+  const finishedAt = nowIso();
+  return {
+    status: "failed",
+    stdout: "",
+    stderr: "",
+    error: `runtime preflight failed: ${error instanceof Error ? error.message : String(error)}`,
+    startedAt,
+    finishedAt,
+    durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+  };
+}
 async function executeLoopTarget(store, loop, run, opts = {}) {
   if (loop.target.type !== "workflow") {
+    if (loop.goal && loop.target.preflight?.beforeRun) {
+      const startedAt = nowIso();
+      try {
+        preflightTarget(loop.target, {
+          loopId: loop.id,
+          loopName: loop.name,
+          runId: run.id,
+          scheduledFor: run.scheduledFor
+        }, { ...opts, machine: opts.machine ?? loop.machine });
+      } catch (error) {
+        return preflightFailureResult(error, startedAt);
+      }
+    }
     if (loop.goal) {
       return runGoal(store, loop.goal, {
         ...opts,
@@ -3732,6 +3779,14 @@ async function executeLoopTarget(store, loop, run, opts = {}) {
     return executeLoop(loop, run, opts);
   }
   const workflow = store.requireWorkflow(loop.target.workflowId);
+  if (loop.target.preflight?.beforeRun) {
+    const startedAt = nowIso();
+    try {
+      preflightWorkflow(workflow, { ...opts, machine: opts.machine ?? loop.machine });
+    } catch (error) {
+      return preflightFailureResult(error, startedAt);
+    }
+  }
   if (loop.goal) {
     return runGoal(store, loop.goal, {
       ...opts,
@@ -4470,7 +4525,7 @@ function enableStartup(result) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.23",
+  version: "0.3.24",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",

package/dist/index.js

@@ -3124,6 +3124,28 @@ async function executeLoop(loop, run, opts = {}) {
   if (loop.target.type === "workflow") {
     throw new Error("workflow loop targets must be executed with executeLoopTarget");
   }
+  if (loop.target.preflight?.beforeRun) {
+    const startedAt = nowIso();
+    try {
+      preflightTarget(loop.target, {
+        loopId: loop.id,
+        loopName: loop.name,
+        runId: run.id,
+        scheduledFor: run.scheduledFor
+      }, { ...opts, machine: opts.machine ?? loop.machine });
+    } catch (error) {
+      const finishedAt = nowIso();
+      return {
+        status: "failed",
+        stdout: "",
+        stderr: "",
+        error: `runtime preflight failed: ${error instanceof Error ? error.message : String(error)}`,
+        startedAt,
+        finishedAt,
+        durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+      };
+    }
+  }
   return executeTarget(loop.target, {
     loopId: loop.id,
     loopName: loop.name,
@@ -3705,8 +3727,33 @@ function preflightWorkflow(workflow, opts = {}) {
     }
   });
 }
+function preflightFailureResult(error, startedAt = nowIso()) {
+  const finishedAt = nowIso();
+  return {
+    status: "failed",
+    stdout: "",
+    stderr: "",
+    error: `runtime preflight failed: ${error instanceof Error ? error.message : String(error)}`,
+    startedAt,
+    finishedAt,
+    durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+  };
+}
 async function executeLoopTarget(store, loop, run, opts = {}) {
   if (loop.target.type !== "workflow") {
+    if (loop.goal && loop.target.preflight?.beforeRun) {
+      const startedAt = nowIso();
+      try {
+        preflightTarget(loop.target, {
+          loopId: loop.id,
+          loopName: loop.name,
+          runId: run.id,
+          scheduledFor: run.scheduledFor
+        }, { ...opts, machine: opts.machine ?? loop.machine });
+      } catch (error) {
+        return preflightFailureResult(error, startedAt);
+      }
+    }
     if (loop.goal) {
       return runGoal(store, loop.goal, {
         ...opts,
@@ -3722,6 +3769,14 @@ async function executeLoopTarget(store, loop, run, opts = {}) {
     return executeLoop(loop, run, opts);
   }
   const workflow = store.requireWorkflow(loop.target.workflowId);
+  if (loop.target.preflight?.beforeRun) {
+    const startedAt = nowIso();
+    try {
+      preflightWorkflow(workflow, { ...opts, machine: opts.machine ?? loop.machine });
+    } catch (error) {
+      return preflightFailureResult(error, startedAt);
+    }
+  }
   if (loop.goal) {
     return runGoal(store, loop.goal, {
       ...opts,
@@ -4796,6 +4851,7 @@ var CLASSIFICATIONS = [
   "context_length",
   "schema_response_format",
   "node_init",
+  "preflight",
   "timeout",
   "sigsegv",
   "skipped_previous_active",
@@ -4843,6 +4899,8 @@ function classifyRunFailure(run) {
     classification = "timeout";
   else if (run.status === "skipped" && /previous run still active/.test(text))
     classification = "skipped_previous_active";
+  else if (/runtime preflight failed|preflight failed|executable not found in path|none of required executables found|auth profile preflight failed|profile not found/.test(text))
+    classification = "preflight";
   else if (/rate limit|too many requests|429\b|quota exceeded/.test(text))
     classification = "rate_limit";
   else if (/unauthorized|authentication|auth\b|api key|invalid token|permission denied|401\b|403\b/.test(text))

package/dist/lib/health.d.ts

@@ -1,6 +1,6 @@
 import type { Loop, LoopRun } from "../types.js";
 import type { Store } from "./store.js";
-export type RunFailureClassification = "rate_limit" | "auth" | "model_not_found" | "context_length" | "schema_response_format" | "node_init" | "timeout" | "sigsegv" | "skipped_previous_active" | "unknown";
+export type RunFailureClassification = "rate_limit" | "auth" | "model_not_found" | "context_length" | "schema_response_format" | "node_init" | "preflight" | "timeout" | "sigsegv" | "skipped_previous_active" | "unknown";
 export interface RunFailureSignal {
     classification: RunFailureClassification;
     fingerprint: string;

package/dist/sdk/index.js

@@ -3124,6 +3124,28 @@ async function executeLoop(loop, run, opts = {}) {
   if (loop.target.type === "workflow") {
     throw new Error("workflow loop targets must be executed with executeLoopTarget");
   }
+  if (loop.target.preflight?.beforeRun) {
+    const startedAt = nowIso();
+    try {
+      preflightTarget(loop.target, {
+        loopId: loop.id,
+        loopName: loop.name,
+        runId: run.id,
+        scheduledFor: run.scheduledFor
+      }, { ...opts, machine: opts.machine ?? loop.machine });
+    } catch (error) {
+      const finishedAt = nowIso();
+      return {
+        status: "failed",
+        stdout: "",
+        stderr: "",
+        error: `runtime preflight failed: ${error instanceof Error ? error.message : String(error)}`,
+        startedAt,
+        finishedAt,
+        durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+      };
+    }
+  }
   return executeTarget(loop.target, {
     loopId: loop.id,
     loopName: loop.name,
@@ -3705,8 +3727,33 @@ function preflightWorkflow(workflow, opts = {}) {
     }
   });
 }
+function preflightFailureResult(error, startedAt = nowIso()) {
+  const finishedAt = nowIso();
+  return {
+    status: "failed",
+    stdout: "",
+    stderr: "",
+    error: `runtime preflight failed: ${error instanceof Error ? error.message : String(error)}`,
+    startedAt,
+    finishedAt,
+    durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+  };
+}
 async function executeLoopTarget(store, loop, run, opts = {}) {
   if (loop.target.type !== "workflow") {
+    if (loop.goal && loop.target.preflight?.beforeRun) {
+      const startedAt = nowIso();
+      try {
+        preflightTarget(loop.target, {
+          loopId: loop.id,
+          loopName: loop.name,
+          runId: run.id,
+          scheduledFor: run.scheduledFor
+        }, { ...opts, machine: opts.machine ?? loop.machine });
+      } catch (error) {
+        return preflightFailureResult(error, startedAt);
+      }
+    }
     if (loop.goal) {
       return runGoal(store, loop.goal, {
         ...opts,
@@ -3722,6 +3769,14 @@ async function executeLoopTarget(store, loop, run, opts = {}) {
     return executeLoop(loop, run, opts);
   }
   const workflow = store.requireWorkflow(loop.target.workflowId);
+  if (loop.target.preflight?.beforeRun) {
+    const startedAt = nowIso();
+    try {
+      preflightWorkflow(workflow, { ...opts, machine: opts.machine ?? loop.machine });
+    } catch (error) {
+      return preflightFailureResult(error, startedAt);
+    }
+  }
   if (loop.goal) {
     return runGoal(store, loop.goal, {
       ...opts,

package/dist/types.d.ts

@@ -40,6 +40,9 @@ export interface DynamicSchedule {
     minIntervalMs?: number;
 }
 export type ScheduleSpec = OnceSchedule | IntervalSchedule | CronSchedule | DynamicSchedule;
+export interface RuntimePreflightPolicy {
+    beforeRun?: boolean;
+}
 export interface CommandTarget {
     type: "command";
     command: string;
@@ -49,6 +52,7 @@ export interface CommandTarget {
     env?: Record<string, string>;
     timeoutMs?: number;
     account?: AccountRef;
+    preflight?: RuntimePreflightPolicy;
 }
 export type AgentProvider = "claude" | "cursor" | "codewith" | "aicopilot" | "opencode" | "codex";
 export type AgentConfigIsolation = "safe" | "none";
@@ -75,12 +79,14 @@ export interface AgentTarget {
     sandbox?: AgentSandbox;
     allowlist?: AgentAllowlistSpec;
     account?: AccountRef;
+    preflight?: RuntimePreflightPolicy;
 }
 export interface WorkflowTarget {
     type: "workflow";
     workflowId: string;
     input?: Record<string, string>;
     timeoutMs?: number;
+    preflight?: RuntimePreflightPolicy;
 }
 export type ExecutableTarget = CommandTarget | AgentTarget;
 export type LoopTarget = ExecutableTarget | WorkflowTarget;

package/docs/USAGE.md

@@ -73,6 +73,12 @@ accounts because the command string is interpreted later by the shell. Use
 `--no-shell` or workflow command `args` when you need executable-level
 validation before storing the loop.
 
+Use `--preflight-each-run` when a loop should repeat the same readiness check at
+run time before launching expensive agent or workflow work. Runtime preflight
+failures are recorded as failed loop runs with a `runtime preflight failed`
+error, so health/routing checks can create follow-up tasks without spawning the
+worker.
+
 Run a Claude loop every morning:
 
 ```bash

package/package.json

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