@hasna/loops 0.3.22 → 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.22",
+  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",
@@ -5662,6 +5720,20 @@ function preflightStoredWorkflow(workflow, context, opts) {
     preflightFailed(error, context);
   }
 }
+function workflowSpecForPreflight(body, id = "validation") {
+  const now = new Date().toISOString();
+  return {
+    id,
+    name: body.name,
+    description: body.description,
+    version: body.version ?? 1,
+    status: "active",
+    goal: body.goal,
+    steps: body.steps,
+    createdAt: now,
+    updatedAt: now
+  };
+}
 function printTextOutput(value) {
   for (const line of textOutputBlocks(value, { indent: "  " }))
     console.log(line);
@@ -5789,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 ?? []) {
@@ -6106,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 = {
@@ -6115,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;
@@ -6125,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");
@@ -6149,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;
@@ -6159,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;
@@ -6211,7 +6289,7 @@ templates.command("create-workflow <id>").description("render and store a templa
   }
 });
 var eventsHandle = events.command("handle").description("handle a Hasna event envelope");
-eventsHandle.command("todos-task").description("create a one-shot worker/verifier workflow loop for a todos task event").option("--provider <provider>", "agent provider", "codewith").option("--auth-profile <profile>", "provider-native auth profile; currently supported for codewith").option("--auth-profile-pool <profiles>", "comma-separated provider-native auth profile pool").option("--worker-auth-profile <profile>", "provider-native auth profile for worker step").option("--verifier-auth-profile <profile>", "provider-native auth profile for verifier step").option("--account <profile>", "OpenAccounts profile name").option("--account-pool <profiles>", "comma-separated OpenAccounts profile pool").option("--worker-account <profile>", "OpenAccounts profile for worker step").option("--verifier-account <profile>", "OpenAccounts profile for verifier step").option("--account-tool <tool>", "OpenAccounts tool id").option("--model <model>", "provider model").option("--variant <variant>", "provider-specific model variant or reasoning effort").option("--agent <agent>", "provider-specific agent").option("--permission-mode <mode>", "provider permission mode: default, plan, auto, or bypass", "bypass").option("--sandbox <mode>", "provider sandbox").option("--project-path <path>", "fallback project/repo working directory").option("--name-prefix <prefix>", "workflow/loop name prefix", "event:todos-task").option("--dry-run", "print the workflow and loop input without storing anything").action(async (opts) => {
+eventsHandle.command("todos-task").description("create a one-shot worker/verifier workflow loop for a todos task event").option("--provider <provider>", "agent provider", "codewith").option("--auth-profile <profile>", "provider-native auth profile; currently supported for codewith").option("--auth-profile-pool <profiles>", "comma-separated provider-native auth profile pool").option("--worker-auth-profile <profile>", "provider-native auth profile for worker step").option("--verifier-auth-profile <profile>", "provider-native auth profile for verifier step").option("--account <profile>", "OpenAccounts profile name").option("--account-pool <profiles>", "comma-separated OpenAccounts profile pool").option("--worker-account <profile>", "OpenAccounts profile for worker step").option("--verifier-account <profile>", "OpenAccounts profile for verifier step").option("--account-tool <tool>", "OpenAccounts tool id").option("--model <model>", "provider model").option("--variant <variant>", "provider-specific model variant or reasoning effort").option("--agent <agent>", "provider-specific agent").option("--permission-mode <mode>", "provider permission mode: default, plan, auto, or bypass", "bypass").option("--sandbox <mode>", "provider sandbox").option("--project-path <path>", "fallback project/repo working directory").option("--name-prefix <prefix>", "workflow/loop name prefix", "event:todos-task").option("--preflight", "check generated workflow steps before storing the workflow loop").option("--dry-run", "print the workflow and loop input without storing anything").action(async (opts) => {
   const event = await readEventEnvelopeFromStdin();
   const data = eventData(event);
   const metadata = eventMetadata(event);
@@ -6280,7 +6358,12 @@ eventsHandle.command("todos-task").description("create a one-shot worker/verifie
     leaseMs: 90 * 60000
   };
   if (opts.dryRun) {
-    print({ deduped: false, idempotencyKey, event, workflow: workflowBody, loop: loopInput }, `dry-run ${loopName}`);
+    const preflight = opts.preflight ? preflightStoredWorkflow(workflowSpecForPreflight(workflowBody, "event-preflight"), {
+      name: workflowBody.name,
+      type: "todos-task-event-workflow",
+      event: event.id
+    }, {}) : undefined;
+    print({ deduped: false, idempotencyKey, event, workflow: workflowBody, loop: loopInput, preflight }, `dry-run ${loopName}`);
     return;
   }
   const store = new Store;
@@ -6299,17 +6382,23 @@ eventsHandle.command("todos-task").description("create a one-shot worker/verifie
       return;
     }
     const existingWorkflow = store.findWorkflowByName(workflowBody.name);
+    const workflowPreflightSpec = existingWorkflow ?? workflowSpecForPreflight(workflowBody, "event-preflight");
+    const preflight = opts.preflight ? preflightStoredWorkflow(workflowPreflightSpec, {
+      name: workflowBody.name,
+      type: "todos-task-event-workflow",
+      event: event.id
+    }, {}) : undefined;
     const workflow = existingWorkflow ?? store.createWorkflow(workflowBody);
     const loop = store.createLoop({
       ...loopInput,
       target: { type: "workflow", workflowId: workflow.id }
     });
-    print({ deduped: false, idempotencyKey, event, workflow: publicWorkflow(workflow), loop: publicLoop(loop) }, `created ${loop.id} (${loop.name}) workflow=${workflow.name} event=${event.id} idempotency=${idempotencyKey}`);
+    print({ deduped: false, idempotencyKey, event, workflow: publicWorkflow(workflow), loop: publicLoop(loop), preflight }, `created ${loop.id} (${loop.name}) workflow=${workflow.name} event=${event.id} idempotency=${idempotencyKey}`);
   } finally {
     store.close();
   }
 });
-eventsHandle.command("generic").description("create a one-shot worker/verifier workflow loop for any Hasna event").option("--provider <provider>", "agent provider", "codewith").option("--auth-profile <profile>", "provider-native auth profile; currently supported for codewith").option("--auth-profile-pool <profiles>", "comma-separated provider-native auth profile pool").option("--worker-auth-profile <profile>", "provider-native auth profile for worker step").option("--verifier-auth-profile <profile>", "provider-native auth profile for verifier step").option("--account <profile>", "OpenAccounts profile name").option("--account-pool <profiles>", "comma-separated OpenAccounts profile pool").option("--worker-account <profile>", "OpenAccounts profile for worker step").option("--verifier-account <profile>", "OpenAccounts profile for verifier step").option("--account-tool <tool>", "OpenAccounts tool id").option("--model <model>", "provider model").option("--variant <variant>", "provider-specific model variant or reasoning effort").option("--agent <agent>", "provider-specific agent").option("--permission-mode <mode>", "provider permission mode: default, plan, auto, or bypass", "bypass").option("--sandbox <mode>", "provider sandbox").option("--project-path <path>", "fallback project/repo working directory").option("--name-prefix <prefix>", "workflow/loop name prefix", "event:generic").option("--dry-run", "print the workflow and loop input without storing anything").action(async (opts) => {
+eventsHandle.command("generic").description("create a one-shot worker/verifier workflow loop for any Hasna event").option("--provider <provider>", "agent provider", "codewith").option("--auth-profile <profile>", "provider-native auth profile; currently supported for codewith").option("--auth-profile-pool <profiles>", "comma-separated provider-native auth profile pool").option("--worker-auth-profile <profile>", "provider-native auth profile for worker step").option("--verifier-auth-profile <profile>", "provider-native auth profile for verifier step").option("--account <profile>", "OpenAccounts profile name").option("--account-pool <profiles>", "comma-separated OpenAccounts profile pool").option("--worker-account <profile>", "OpenAccounts profile for worker step").option("--verifier-account <profile>", "OpenAccounts profile for verifier step").option("--account-tool <tool>", "OpenAccounts tool id").option("--model <model>", "provider model").option("--variant <variant>", "provider-specific model variant or reasoning effort").option("--agent <agent>", "provider-specific agent").option("--permission-mode <mode>", "provider permission mode: default, plan, auto, or bypass", "bypass").option("--sandbox <mode>", "provider sandbox").option("--project-path <path>", "fallback project/repo working directory").option("--name-prefix <prefix>", "workflow/loop name prefix", "event:generic").option("--preflight", "check generated workflow steps before storing the workflow loop").option("--dry-run", "print the workflow and loop input without storing anything").action(async (opts) => {
   const event = await readEventEnvelopeFromStdin();
   const data = eventData(event);
   const projectPath = opts.projectPath ?? taskEventField(data, ["working_dir", "workingDir", "project_path", "projectPath", "cwd", "repo_path", "repoPath"]) ?? process.cwd();
@@ -6359,7 +6448,12 @@ eventsHandle.command("generic").description("create a one-shot worker/verifier w
     leaseMs: 90 * 60000
   };
   if (opts.dryRun) {
-    print({ event, workflow: workflowBody, loop: loopInput }, `dry-run ${loopName}`);
+    const preflight = opts.preflight ? preflightStoredWorkflow(workflowSpecForPreflight(workflowBody, "event-preflight"), {
+      name: workflowBody.name,
+      type: "generic-event-workflow",
+      event: event.id
+    }, {}) : undefined;
+    print({ event, workflow: workflowBody, loop: loopInput, preflight }, `dry-run ${loopName}`);
     return;
   }
   const store = new Store;
@@ -6371,12 +6465,18 @@ eventsHandle.command("generic").description("create a one-shot worker/verifier w
       return;
     }
     const existingWorkflow = store.findWorkflowByName(workflowBody.name);
+    const workflowPreflightSpec = existingWorkflow ?? workflowSpecForPreflight(workflowBody, "event-preflight");
+    const preflight = opts.preflight ? preflightStoredWorkflow(workflowPreflightSpec, {
+      name: workflowBody.name,
+      type: "generic-event-workflow",
+      event: event.id
+    }, {}) : undefined;
     const workflow = existingWorkflow ?? store.createWorkflow(workflowBody);
     const loop = store.createLoop({
       ...loopInput,
       target: { type: "workflow", workflowId: workflow.id }
     });
-    print({ deduped: false, event, workflow: publicWorkflow(workflow), loop: publicLoop(loop) }, `created ${loop.id} (${loop.name}) workflow=${workflow.name}`);
+    print({ deduped: false, event, workflow: publicWorkflow(workflow), loop: publicLoop(loop), preflight }, `created ${loop.id} (${loop.name}) workflow=${workflow.name}`);
   } finally {
     store.close();
   }
@@ -6441,27 +6541,20 @@ machines.command("show <id>").description("resolve a machine assignment").action
 });
 workflows.command("validate <file>").description("validate a workflow JSON file without storing or running it").option("--name <name>", "override workflow name from the file").option("--preflight", "also check account env and target executables").action((file, opts) => {
   const body = workflowBodyFromJson(JSON.parse(readFileSync2(file, "utf8")), opts.name);
-  const now = new Date().toISOString();
-  const workflow = {
-    id: "validation",
-    name: body.name,
-    description: body.description,
-    version: body.version ?? 1,
-    status: "active",
-    goal: body.goal,
-    steps: body.steps,
-    createdAt: now,
-    updatedAt: now
-  };
+  const workflow = workflowSpecForPreflight(body);
   const preflight = opts.preflight ? preflightWorkflow(workflow) : undefined;
   print({ valid: true, workflow: publicWorkflow(workflow), preflight }, `valid workflow ${workflow.name} steps=${workflow.steps.length}`);
 });
-workflows.command("create <file>").description("validate and store a workflow JSON file").option("--name <name>", "override workflow name from the file").action((file, opts) => {
+workflows.command("create <file>").description("validate and store a workflow JSON file").option("--name <name>", "override workflow name from the file").option("--preflight", "also check account env and target executables before storing").action((file, opts) => {
   const store = new Store;
   try {
     const body = workflowBodyFromJson(JSON.parse(readFileSync2(file, "utf8")), opts.name);
+    const preflight = opts.preflight ? preflightStoredWorkflow(workflowSpecForPreflight(body, "creation-preflight"), { name: body.name, type: "workflow" }, {}) : undefined;
     const workflow = store.createWorkflow(body);
-    print(publicWorkflow(workflow), `created workflow ${workflow.id} (${workflow.name}) steps=${workflow.steps.length}`);
+    if (preflight !== undefined)
+      print({ workflow: publicWorkflow(workflow), preflight }, `created workflow ${workflow.id} (${workflow.name}) steps=${workflow.steps.length}`);
+    else
+      print(publicWorkflow(workflow), `created workflow ${workflow.id} (${workflow.name}) steps=${workflow.steps.length}`);
   } finally {
     store.close();
   }

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.22",
+  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

@@ -59,10 +59,12 @@ loops create command repo-status \
   --preflight
 ```
 
-`--preflight` is available on `loops create command`, `loops create agent`, and
-`loops create workflow`. It checks target executables and configured account
-profiles before the loop row is stored, so a missing command, provider binary,
-OpenAccounts profile, or workflow step dependency fails without creating a
+`--preflight` is available on `loops create command`, `loops create agent`,
+`loops create workflow`, `loops workflows create`, and event-router commands such
+as `loops events handle todos-task` and `loops events handle generic`. It checks
+target executables and configured account profiles before loop or workflow rows
+are stored, so a missing command, provider binary, OpenAccounts profile, native
+Codewith auth profile, or workflow step dependency fails without creating a
 scheduled loop. Use `--json` with `--preflight` to capture stable machine-readable
 preflight evidence.
 
@@ -71,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.22",
+  "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",