@hasna/loops 0.3.15 → 0.3.16

package/dist/cli/index.js

@@ -328,6 +328,17 @@ function optionalPositiveInteger(value, label) {
     throw new Error(`${label} must be a positive integer`);
   return value;
 }
+function optionalStringArray(value, label) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value))
+    throw new Error(`${label} must be an array`);
+  const values = value.map((entry, index) => {
+    assertString(entry, `${label}[${index}]`);
+    return entry.trim();
+  }).filter(Boolean);
+  return values.length ? values : undefined;
+}
 function normalizeGoalSpec(value, label = "goal") {
   if (value === undefined)
     return;
@@ -399,6 +410,14 @@ function validateTarget(value, label) {
         throw new Error(`${label}.sandbox is currently supported only for provider codewith, codex, or cursor`);
       }
     }
+    if (value.allowlist !== undefined) {
+      assertObject(value.allowlist, `${label}.allowlist`);
+      optionalStringArray(value.allowlist.tools, `${label}.allowlist.tools`);
+      optionalStringArray(value.allowlist.commands, `${label}.allowlist.commands`);
+      if (value.allowlist.enforcement !== undefined && value.allowlist.enforcement !== "metadata_only") {
+        throw new Error(`${label}.allowlist.enforcement must be metadata_only`);
+      }
+    }
     return value;
   }
   throw new Error(`${label}.type must be command or agent`);
@@ -2152,7 +2171,7 @@ class Store {
 }
 
 // src/cli/index.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
 import { Command } from "commander";
 
@@ -2571,6 +2590,16 @@ function metadataEnv(metadata) {
     env.LOOPS_GOAL_NODE_KEY = metadata.goalNodeKey;
   return env;
 }
+function allowlistEnv(allowlist) {
+  const env = {};
+  if (allowlist?.tools?.length)
+    env.LOOPS_AGENT_ALLOWED_TOOLS = allowlist.tools.join(",");
+  if (allowlist?.commands?.length)
+    env.LOOPS_AGENT_ALLOWED_COMMANDS = allowlist.commands.join(",");
+  if (allowlist?.tools?.length || allowlist?.commands?.length)
+    env.LOOPS_AGENT_ALLOWLIST_ENFORCEMENT = "metadata_only";
+  return env;
+}
 function providerCommand(provider) {
   switch (provider) {
     case "claude":
@@ -2778,7 +2807,8 @@ function commandSpec(target) {
     account: agentTarget.account,
     accountTool: agentTarget.account?.tool ?? accountToolForProvider(agentTarget.provider),
     preflightAnyOf: agentTarget.provider === "cursor" ? ["cursor", "agent"] : undefined,
-    stdin: agentTarget.prompt
+    stdin: agentTarget.prompt,
+    allowlist: agentTarget.allowlist
   };
 }
 function executionEnv(spec, metadata, opts) {
@@ -2790,6 +2820,7 @@ function executionEnv(spec, metadata, opts) {
     Object.assign(env, accountEnv);
   }
   Object.assign(env, spec.env ?? {});
+  Object.assign(env, allowlistEnv(spec.allowlist));
   env.PATH = normalizeExecutionPath(env);
   Object.assign(env, metadataEnv(metadata));
   return env;
@@ -2828,6 +2859,9 @@ function remoteBootstrapLines(spec, metadata) {
       continue;
     lines.push(`export ${key}=${shellQuote(value)}`);
   }
+  for (const [key, value] of Object.entries(allowlistEnv(spec.allowlist))) {
+    lines.push(`export ${key}=${shellQuote(value)}`);
+  }
   return lines;
 }
 function remoteScript(spec, metadata) {
@@ -4577,10 +4611,220 @@ function runDoctor(store) {
     checks
   };
 }
+
+// src/lib/health.ts
+import { createHash } from "crypto";
+var EVIDENCE_CHARS = 2000;
+var CLASSIFICATIONS = [
+  "rate_limit",
+  "auth",
+  "model_not_found",
+  "context_length",
+  "schema_response_format",
+  "node_init",
+  "timeout",
+  "sigsegv",
+  "skipped_previous_active",
+  "unknown"
+];
+function bounded(value, limit = EVIDENCE_CHARS) {
+  if (!value)
+    return;
+  if (value.length <= limit)
+    return value;
+  return `${value.slice(0, limit)}
+[truncated ${value.length - limit} chars]`;
+}
+function searchableText(run) {
+  return [run.error, run.stderr, run.stdout].filter(Boolean).join(`
+`).toLowerCase();
+}
+function stableFingerprint(parts) {
+  return createHash("sha256").update(parts.join(`
+`)).digest("hex").slice(0, 16);
+}
+function healthRun(run) {
+  return {
+    ...run,
+    error: bounded(run.error),
+    stdout: bounded(run.stdout),
+    stderr: bounded(run.stderr)
+  };
+}
+function classifyRunFailure(run) {
+  if (run.status === "succeeded" || run.status === "running")
+    return;
+  const text = searchableText(run);
+  let classification = "unknown";
+  if (run.status === "timed_out")
+    classification = "timeout";
+  else if (run.status === "skipped" && /previous run still active/.test(text))
+    classification = "skipped_previous_active";
+  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))
+    classification = "auth";
+  else if (/model .*not found|model_not_found|unknown model|invalid model|404.*model/.test(text))
+    classification = "model_not_found";
+  else if (/context length|context_length|context window|maximum context|token limit|too many tokens/.test(text))
+    classification = "context_length";
+  else if (/response_format|json schema|schema validation|invalid schema|structured output/.test(text))
+    classification = "schema_response_format";
+  else if (/cannot find module|module not found|node:internal|bun: command not found|node: command not found|npm err!|err_module_not_found/.test(text))
+    classification = "node_init";
+  else if (/sigsegv|segmentation fault|signal 11/.test(text))
+    classification = "sigsegv";
+  return {
+    classification,
+    fingerprint: stableFingerprint([
+      run.loopId,
+      run.loopName,
+      run.status,
+      classification,
+      String(run.exitCode ?? ""),
+      (run.error ?? run.stderr ?? run.stdout ?? "").slice(0, 500)
+    ]),
+    evidence: {
+      error: bounded(run.error),
+      stdout: bounded(run.stdout),
+      stderr: bounded(run.stderr),
+      exitCode: run.exitCode
+    }
+  };
+}
+function targetRoute(loop) {
+  if (loop.target.type === "agent") {
+    return {
+      source: "openloops",
+      kind: "loop_expectation",
+      loopId: loop.id,
+      loopName: loop.name,
+      cwd: loop.target.cwd,
+      provider: loop.target.provider
+    };
+  }
+  if (loop.target.type === "command") {
+    return {
+      source: "openloops",
+      kind: "loop_expectation",
+      loopId: loop.id,
+      loopName: loop.name,
+      cwd: loop.target.cwd
+    };
+  }
+  return {
+    source: "openloops",
+    kind: "loop_expectation",
+    loopId: loop.id,
+    loopName: loop.name
+  };
+}
+function recommendedTask(loop, run, failure, route) {
+  const title = `BUG: open-loops loop failure - ${loop.name}`;
+  const description = [
+    `OpenLoops expectation failed for loop ${loop.name} (${loop.id}).`,
+    `Run: ${run.id}`,
+    `Status: ${run.status}`,
+    `Classification: ${failure.classification}`,
+    `Fingerprint: ${failure.fingerprint}`,
+    route.cwd ? `Route cwd: ${route.cwd}` : undefined,
+    route.provider ? `Provider: ${route.provider}` : undefined,
+    failure.evidence.error ? `Error:
+${failure.evidence.error}` : undefined,
+    failure.evidence.stderr ? `Stderr:
+${failure.evidence.stderr}` : undefined
+  ].filter(Boolean).join(`
+
+`);
+  const dedupeKey = `openloops:${loop.id}:${failure.fingerprint}`;
+  const tags = ["bug", "openloops", "loop-health", failure.classification];
+  const priority = failure.classification === "auth" || failure.classification === "rate_limit" ? "high" : "medium";
+  return {
+    title,
+    description,
+    priority,
+    tags,
+    dedupeKey,
+    search: { query: dedupeKey },
+    compatibilityFallback: {
+      search: ["todos", "search", dedupeKey, "--json"],
+      add: ["todos", "add", title, "--description", description, "--tag", tags.join(","), "--priority", priority],
+      comment: ["todos", "comment", "<task-id>", description]
+    },
+    futureNativeUpsert: {
+      command: "todos upsert",
+      fields: {
+        title,
+        description,
+        priority,
+        tags,
+        dedupeKey,
+        routeSource: route.source,
+        routeKind: route.kind,
+        routeLoopId: route.loopId,
+        routeLoopName: route.loopName
+      }
+    }
+  };
+}
+function expectationForLoop(store, loop) {
+  const latestRun = store.listRuns({ loopId: loop.id, limit: 1 })[0];
+  const route = targetRoute(loop);
+  if (!latestRun) {
+    return {
+      loop: { id: loop.id, name: loop.name, status: loop.status, nextRunAt: loop.nextRunAt },
+      ok: true,
+      check: { id: "latest-run-succeeded", status: "warn", message: "loop has no recorded runs yet" },
+      route
+    };
+  }
+  if (latestRun.status === "succeeded") {
+    return {
+      loop: { id: loop.id, name: loop.name, status: loop.status, nextRunAt: loop.nextRunAt },
+      ok: true,
+      check: { id: "latest-run-succeeded", status: "pass", message: "latest run succeeded" },
+      latestRun: healthRun(latestRun),
+      route
+    };
+  }
+  const failure = classifyRunFailure(latestRun);
+  return {
+    loop: { id: loop.id, name: loop.name, status: loop.status, nextRunAt: loop.nextRunAt },
+    ok: false,
+    check: { id: "latest-run-succeeded", status: "fail", message: `latest run is ${latestRun.status}` },
+    latestRun: healthRun(latestRun),
+    failure,
+    route,
+    recommendedTask: failure ? recommendedTask(loop, latestRun, failure, route) : undefined
+  };
+}
+function buildHealthReport(store, opts = {}) {
+  const loops = store.listLoops({ includeArchived: opts.includeArchived, limit: opts.limit ?? 200 });
+  const expectations = loops.map((loop) => expectationForLoop(store, loop));
+  const classifications = Object.fromEntries(CLASSIFICATIONS.map((key) => [key, 0]));
+  for (const expectation of expectations) {
+    if (expectation.failure)
+      classifications[expectation.failure.classification] += 1;
+  }
+  const unhealthy = expectations.filter((expectation) => !expectation.ok).length;
+  const warnings = expectations.filter((expectation) => expectation.check.status === "warn").length;
+  return {
+    ok: unhealthy === 0,
+    generatedAt: new Date().toISOString(),
+    summary: {
+      loops: expectations.length,
+      healthy: expectations.length - unhealthy,
+      unhealthy,
+      warnings
+    },
+    classifications,
+    expectations
+  };
+}
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.15",
+  version: "0.3.16",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -5080,6 +5324,17 @@ function splitList(value) {
   const values = value?.split(",").map((entry) => entry.trim()).filter(Boolean);
   return values?.length ? values : undefined;
 }
+function allowlistFromOpts(opts) {
+  const tools = (opts.allowTool ?? []).flatMap((entry) => splitList(entry) ?? []);
+  const commands = (opts.allowCommand ?? []).flatMap((entry) => splitList(entry) ?? []);
+  if (!tools.length && !commands.length)
+    return;
+  return {
+    tools: tools.length ? tools : undefined,
+    commands: commands.length ? commands : undefined,
+    enforcement: "metadata_only"
+  };
+}
 function accountPoolFromOpts(opts) {
   return splitList(opts.accountPool)?.map((profile) => ({ profile, tool: opts.accountTool }));
 }
@@ -5119,7 +5374,7 @@ function slugSegment(value, fallback = "event") {
   return value.toLowerCase().replace(/[^a-z0-9._:-]+/g, "-").replace(/^-|-$/g, "").slice(0, 80) || fallback;
 }
 function stableSuffix(value) {
-  return createHash("sha256").update(value).digest("hex").slice(0, 12);
+  return createHash2("sha256").update(value).digest("hex").slice(0, 12);
 }
 function taskEventField(data, keys) {
   for (const key of keys) {
@@ -5145,6 +5400,85 @@ function taskEventField(data, keys) {
   }
   return;
 }
+function objectField(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function nestedObject(input, key) {
+  return objectField(input[key]);
+}
+function taskEventRecords(data, metadata) {
+  const records = [data];
+  const dataTask = nestedObject(data, "task");
+  if (dataTask)
+    records.push(dataTask);
+  const dataPayload = nestedObject(data, "payload");
+  if (dataPayload) {
+    records.push(dataPayload);
+    const payloadTask = nestedObject(dataPayload, "task");
+    if (payloadTask)
+      records.push(payloadTask);
+  }
+  const dataMetadata = nestedObject(data, "metadata");
+  if (dataMetadata)
+    records.push(dataMetadata);
+  records.push(metadata);
+  const metadataTask = nestedObject(metadata, "task");
+  if (metadataTask)
+    records.push(metadataTask);
+  const metadataAutomation = nestedObject(metadata, "automation");
+  if (metadataAutomation)
+    records.push(metadataAutomation);
+  return records;
+}
+function booleanLike(value) {
+  return value === true || value === "true" || value === "1" || value === 1;
+}
+function hasTruthyField(records, keys) {
+  return records.some((record) => keys.some((key) => booleanLike(record[key])));
+}
+function tagsFromValue(value) {
+  if (Array.isArray(value))
+    return value.map((entry) => String(entry).trim()).filter(Boolean);
+  if (typeof value === "string")
+    return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+  return [];
+}
+function taskEventTags(records) {
+  const tags = new Set;
+  for (const record of records) {
+    for (const tag of tagsFromValue(record.tags ?? record.task_tags ?? record.taskTags))
+      tags.add(tag);
+  }
+  return [...tags];
+}
+function taskRouteEligibility(data, metadata) {
+  const records = taskEventRecords(data, metadata);
+  const tags = taskEventTags(records);
+  const hasRouteOptIn = tags.includes("auto:route") || hasTruthyField(records, ["route_enabled", "routeEnabled", "automation_allowed", "automationAllowed", "allowed"]);
+  if (!hasRouteOptIn)
+    return { eligible: false, reason: "missing explicit route opt-in", tags };
+  const status = taskEventField(data, ["status", "task_status", "taskStatus"])?.toLowerCase();
+  if (status && ["blocked", "completed", "done", "cancelled", "canceled", "failed", "archived"].includes(status)) {
+    return { eligible: false, reason: `task status is not routable: ${status}`, tags };
+  }
+  const disallowedTags = tags.filter((tag) => ["no-auto", "manual", "manual-required", "approval-required"].includes(tag));
+  if (disallowedTags.length)
+    return { eligible: false, reason: `task has disallowed tag: ${disallowedTags[0]}`, tags };
+  if (hasTruthyField(records, [
+    "no_auto",
+    "noAuto",
+    "manual",
+    "manual_required",
+    "manualRequired",
+    "requires_approval",
+    "requiresApproval",
+    "approval_required",
+    "approvalRequired"
+  ])) {
+    return { eligible: false, reason: "task metadata requires manual or approval-gated handling", tags };
+  }
+  return { eligible: true, tags };
+}
 async function readEventEnvelopeFromStdin() {
   const raw = process.env.HASNA_EVENT_JSON || await Bun.stdin.text();
   const event = JSON.parse(raw);
@@ -5217,7 +5551,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("--config-isolation <mode>", "safe or none", "safe"))))).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"))))).action((name, opts) => {
   const provider = opts.provider;
   if (!["claude", "cursor", "codewith", "aicopilot", "opencode", "codex"].includes(provider)) {
     throw new Error("unsupported provider");
@@ -5240,6 +5574,7 @@ addGoalOptions(addAccountOptions(addMachineOptions(addScheduleOptions(create.com
       configIsolation: opts.configIsolation,
       permissionMode: permissionModeFromOpts(opts, provider),
       sandbox: sandboxFromOpts(opts, provider),
+      allowlist: allowlistFromOpts(opts),
       account: accountFromOpts(opts)
     };
     const loop = store.createLoop(baseCreateInput(name, opts, target));
@@ -5305,6 +5640,11 @@ eventsHandle.command("todos-task").description("create a one-shot worker/verifie
   const taskId = taskEventField(data, ["id", "task_id", "taskId"]);
   if (!taskId)
     throw new Error("todos task event is missing task id in data.id, data.task_id, data.task.id, or data.payload.id");
+  const eligibility = taskRouteEligibility(data, metadata);
+  if (!eligibility.eligible) {
+    print({ skipped: true, reason: eligibility.reason, event, taskId, eligibility }, `skipped task ${taskId}: ${eligibility.reason}`);
+    return;
+  }
   const taskTitle = taskEventField(data, ["title", "task_title", "taskTitle"]);
   const taskDescription = taskEventField(data, ["description", "body"]);
   const dataProjectPath = taskEventField(data, ["working_dir", "workingDir", "project_path", "projectPath", "cwd"]);
@@ -5729,6 +6069,44 @@ program.command("runs [idOrName]").option("--limit <n>", "limit", "50").option("
     store.close();
   }
 });
+program.command("expectations [idOrName]").description("evaluate deterministic loop expectations without mutating external task systems").option("--limit <n>", "maximum loops to inspect when no loop is specified", "200").option("--json", "print JSON").action((idOrName, opts) => {
+  const store = new Store;
+  try {
+    const loops = idOrName ? [store.requireLoop(idOrName)] : store.listLoops({ limit: Number(opts.limit) });
+    const values = loops.map((loop) => expectationForLoop(store, loop));
+    if (isJson() || opts.json)
+      console.log(JSON.stringify(idOrName ? values[0] : values, null, 2));
+    else {
+      for (const value of values) {
+        console.log(`${value.ok ? "ok" : "fail"}  ${value.loop.name}  ${value.check.message}`);
+        if (value.failure)
+          console.log(`  classification=${value.failure.classification} fingerprint=${value.failure.fingerprint}`);
+      }
+    }
+    if (values.some((value) => !value.ok))
+      process.exitCode = 1;
+  } finally {
+    store.close();
+  }
+});
+program.command("health").description("summarize loop health and latest-run expectation status").option("--json", "print JSON").action((opts) => {
+  const store = new Store;
+  try {
+    const report = buildHealthReport(store);
+    if (isJson() || opts.json)
+      console.log(JSON.stringify(report, null, 2));
+    else {
+      console.log(`loops=${report.summary.loops} healthy=${report.summary.healthy} unhealthy=${report.summary.unhealthy} warnings=${report.summary.warnings}`);
+      for (const expectation of report.expectations.filter((entry) => !entry.ok)) {
+        console.log(`fail  ${expectation.loop.name}  ${expectation.failure?.classification ?? "unknown"}  ${expectation.failure?.fingerprint ?? "-"}`);
+      }
+    }
+    if (!report.ok)
+      process.exitCode = 1;
+  } finally {
+    store.close();
+  }
+});
 program.command("pause <idOrName>").action((idOrName) => updateStatus(idOrName, "paused"));
 program.command("resume <idOrName>").action((idOrName) => updateStatus(idOrName, "active"));
 program.command("stop <idOrName>").action((idOrName) => updateStatus(idOrName, "stopped"));

package/dist/daemon/index.js

@@ -328,6 +328,17 @@ function optionalPositiveInteger(value, label) {
     throw new Error(`${label} must be a positive integer`);
   return value;
 }
+function optionalStringArray(value, label) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value))
+    throw new Error(`${label} must be an array`);
+  const values = value.map((entry, index) => {
+    assertString(entry, `${label}[${index}]`);
+    return entry.trim();
+  }).filter(Boolean);
+  return values.length ? values : undefined;
+}
 function normalizeGoalSpec(value, label = "goal") {
   if (value === undefined)
     return;
@@ -399,6 +410,14 @@ function validateTarget(value, label) {
         throw new Error(`${label}.sandbox is currently supported only for provider codewith, codex, or cursor`);
       }
     }
+    if (value.allowlist !== undefined) {
+      assertObject(value.allowlist, `${label}.allowlist`);
+      optionalStringArray(value.allowlist.tools, `${label}.allowlist.tools`);
+      optionalStringArray(value.allowlist.commands, `${label}.allowlist.commands`);
+      if (value.allowlist.enforcement !== undefined && value.allowlist.enforcement !== "metadata_only") {
+        throw new Error(`${label}.allowlist.enforcement must be metadata_only`);
+      }
+    }
     return value;
   }
   throw new Error(`${label}.type must be command or agent`);
@@ -2465,6 +2484,16 @@ function metadataEnv(metadata) {
     env.LOOPS_GOAL_NODE_KEY = metadata.goalNodeKey;
   return env;
 }
+function allowlistEnv(allowlist) {
+  const env = {};
+  if (allowlist?.tools?.length)
+    env.LOOPS_AGENT_ALLOWED_TOOLS = allowlist.tools.join(",");
+  if (allowlist?.commands?.length)
+    env.LOOPS_AGENT_ALLOWED_COMMANDS = allowlist.commands.join(",");
+  if (allowlist?.tools?.length || allowlist?.commands?.length)
+    env.LOOPS_AGENT_ALLOWLIST_ENFORCEMENT = "metadata_only";
+  return env;
+}
 function providerCommand(provider) {
   switch (provider) {
     case "claude":
@@ -2672,7 +2701,8 @@ function commandSpec(target) {
     account: agentTarget.account,
     accountTool: agentTarget.account?.tool ?? accountToolForProvider(agentTarget.provider),
     preflightAnyOf: agentTarget.provider === "cursor" ? ["cursor", "agent"] : undefined,
-    stdin: agentTarget.prompt
+    stdin: agentTarget.prompt,
+    allowlist: agentTarget.allowlist
   };
 }
 function executionEnv(spec, metadata, opts) {
@@ -2684,6 +2714,7 @@ function executionEnv(spec, metadata, opts) {
     Object.assign(env, accountEnv);
   }
   Object.assign(env, spec.env ?? {});
+  Object.assign(env, allowlistEnv(spec.allowlist));
   env.PATH = normalizeExecutionPath(env);
   Object.assign(env, metadataEnv(metadata));
   return env;
@@ -2722,6 +2753,9 @@ function remoteBootstrapLines(spec, metadata) {
       continue;
     lines.push(`export ${key}=${shellQuote(value)}`);
   }
+  for (const [key, value] of Object.entries(allowlistEnv(spec.allowlist))) {
+    lines.push(`export ${key}=${shellQuote(value)}`);
+  }
   return lines;
 }
 function remoteScript(spec, metadata) {
@@ -4361,7 +4395,7 @@ function enableStartup(result) {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.3.15",
+  version: "0.3.16",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { executeWorkflow, executeLoopTarget, preflightWorkflow } from "./lib/wor
 export { workflowExecutionOrder, workflowBodyFromJson } from "./lib/workflow-spec.js";
 export { EVENT_WORKER_VERIFIER_TEMPLATE_ID, TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID, getLoopTemplate, listLoopTemplates, renderEventWorkerVerifierWorkflow, renderLoopTemplate, renderTodosTaskWorkerVerifierWorkflow, } from "./lib/templates.js";
 export { runDoctor } from "./lib/doctor.js";
+export { buildHealthReport, classifyRunFailure, expectationForLoop } from "./lib/health.js";
 export { runGoal } from "./lib/goal/runner.js";
 export { resolveGoalModel } from "./lib/goal/model-factory.js";
 export { isTerminal as isGoalTerminal, readyNodeKeys, rollupSummary } from "./lib/goal/status.js";

package/dist/index.js

@@ -326,6 +326,17 @@ function optionalPositiveInteger(value, label) {
     throw new Error(`${label} must be a positive integer`);
   return value;
 }
+function optionalStringArray(value, label) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value))
+    throw new Error(`${label} must be an array`);
+  const values = value.map((entry, index) => {
+    assertString(entry, `${label}[${index}]`);
+    return entry.trim();
+  }).filter(Boolean);
+  return values.length ? values : undefined;
+}
 function normalizeGoalSpec(value, label = "goal") {
   if (value === undefined)
     return;
@@ -397,6 +408,14 @@ function validateTarget(value, label) {
         throw new Error(`${label}.sandbox is currently supported only for provider codewith, codex, or cursor`);
       }
     }
+    if (value.allowlist !== undefined) {
+      assertObject(value.allowlist, `${label}.allowlist`);
+      optionalStringArray(value.allowlist.tools, `${label}.allowlist.tools`);
+      optionalStringArray(value.allowlist.commands, `${label}.allowlist.commands`);
+      if (value.allowlist.enforcement !== undefined && value.allowlist.enforcement !== "metadata_only") {
+        throw new Error(`${label}.allowlist.enforcement must be metadata_only`);
+      }
+    }
     return value;
   }
   throw new Error(`${label}.type must be command or agent`);
@@ -2455,6 +2474,16 @@ function metadataEnv(metadata) {
     env.LOOPS_GOAL_NODE_KEY = metadata.goalNodeKey;
   return env;
 }
+function allowlistEnv(allowlist) {
+  const env = {};
+  if (allowlist?.tools?.length)
+    env.LOOPS_AGENT_ALLOWED_TOOLS = allowlist.tools.join(",");
+  if (allowlist?.commands?.length)
+    env.LOOPS_AGENT_ALLOWED_COMMANDS = allowlist.commands.join(",");
+  if (allowlist?.tools?.length || allowlist?.commands?.length)
+    env.LOOPS_AGENT_ALLOWLIST_ENFORCEMENT = "metadata_only";
+  return env;
+}
 function providerCommand(provider) {
   switch (provider) {
     case "claude":
@@ -2662,7 +2691,8 @@ function commandSpec(target) {
     account: agentTarget.account,
     accountTool: agentTarget.account?.tool ?? accountToolForProvider(agentTarget.provider),
     preflightAnyOf: agentTarget.provider === "cursor" ? ["cursor", "agent"] : undefined,
-    stdin: agentTarget.prompt
+    stdin: agentTarget.prompt,
+    allowlist: agentTarget.allowlist
   };
 }
 function executionEnv(spec, metadata, opts) {
@@ -2674,6 +2704,7 @@ function executionEnv(spec, metadata, opts) {
     Object.assign(env, accountEnv);
   }
   Object.assign(env, spec.env ?? {});
+  Object.assign(env, allowlistEnv(spec.allowlist));
   env.PATH = normalizeExecutionPath(env);
   Object.assign(env, metadataEnv(metadata));
   return env;
@@ -2712,6 +2743,9 @@ function remoteBootstrapLines(spec, metadata) {
       continue;
     lines.push(`export ${key}=${shellQuote(value)}`);
   }
+  for (const [key, value] of Object.entries(allowlistEnv(spec.allowlist))) {
+    lines.push(`export ${key}=${shellQuote(value)}`);
+  }
   return lines;
 }
 function remoteScript(spec, metadata) {
@@ -4582,6 +4616,215 @@ function runDoctor(store) {
     checks
   };
 }
+// src/lib/health.ts
+import { createHash } from "crypto";
+var EVIDENCE_CHARS = 2000;
+var CLASSIFICATIONS = [
+  "rate_limit",
+  "auth",
+  "model_not_found",
+  "context_length",
+  "schema_response_format",
+  "node_init",
+  "timeout",
+  "sigsegv",
+  "skipped_previous_active",
+  "unknown"
+];
+function bounded(value, limit = EVIDENCE_CHARS) {
+  if (!value)
+    return;
+  if (value.length <= limit)
+    return value;
+  return `${value.slice(0, limit)}
+[truncated ${value.length - limit} chars]`;
+}
+function searchableText(run) {
+  return [run.error, run.stderr, run.stdout].filter(Boolean).join(`
+`).toLowerCase();
+}
+function stableFingerprint(parts) {
+  return createHash("sha256").update(parts.join(`
+`)).digest("hex").slice(0, 16);
+}
+function healthRun(run) {
+  return {
+    ...run,
+    error: bounded(run.error),
+    stdout: bounded(run.stdout),
+    stderr: bounded(run.stderr)
+  };
+}
+function classifyRunFailure(run) {
+  if (run.status === "succeeded" || run.status === "running")
+    return;
+  const text = searchableText(run);
+  let classification = "unknown";
+  if (run.status === "timed_out")
+    classification = "timeout";
+  else if (run.status === "skipped" && /previous run still active/.test(text))
+    classification = "skipped_previous_active";
+  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))
+    classification = "auth";
+  else if (/model .*not found|model_not_found|unknown model|invalid model|404.*model/.test(text))
+    classification = "model_not_found";
+  else if (/context length|context_length|context window|maximum context|token limit|too many tokens/.test(text))
+    classification = "context_length";
+  else if (/response_format|json schema|schema validation|invalid schema|structured output/.test(text))
+    classification = "schema_response_format";
+  else if (/cannot find module|module not found|node:internal|bun: command not found|node: command not found|npm err!|err_module_not_found/.test(text))
+    classification = "node_init";
+  else if (/sigsegv|segmentation fault|signal 11/.test(text))
+    classification = "sigsegv";
+  return {
+    classification,
+    fingerprint: stableFingerprint([
+      run.loopId,
+      run.loopName,
+      run.status,
+      classification,
+      String(run.exitCode ?? ""),
+      (run.error ?? run.stderr ?? run.stdout ?? "").slice(0, 500)
+    ]),
+    evidence: {
+      error: bounded(run.error),
+      stdout: bounded(run.stdout),
+      stderr: bounded(run.stderr),
+      exitCode: run.exitCode
+    }
+  };
+}
+function targetRoute(loop) {
+  if (loop.target.type === "agent") {
+    return {
+      source: "openloops",
+      kind: "loop_expectation",
+      loopId: loop.id,
+      loopName: loop.name,
+      cwd: loop.target.cwd,
+      provider: loop.target.provider
+    };
+  }
+  if (loop.target.type === "command") {
+    return {
+      source: "openloops",
+      kind: "loop_expectation",
+      loopId: loop.id,
+      loopName: loop.name,
+      cwd: loop.target.cwd
+    };
+  }
+  return {
+    source: "openloops",
+    kind: "loop_expectation",
+    loopId: loop.id,
+    loopName: loop.name
+  };
+}
+function recommendedTask(loop, run, failure, route) {
+  const title = `BUG: open-loops loop failure - ${loop.name}`;
+  const description = [
+    `OpenLoops expectation failed for loop ${loop.name} (${loop.id}).`,
+    `Run: ${run.id}`,
+    `Status: ${run.status}`,
+    `Classification: ${failure.classification}`,
+    `Fingerprint: ${failure.fingerprint}`,
+    route.cwd ? `Route cwd: ${route.cwd}` : undefined,
+    route.provider ? `Provider: ${route.provider}` : undefined,
+    failure.evidence.error ? `Error:
+${failure.evidence.error}` : undefined,
+    failure.evidence.stderr ? `Stderr:
+${failure.evidence.stderr}` : undefined
+  ].filter(Boolean).join(`
+
+`);
+  const dedupeKey = `openloops:${loop.id}:${failure.fingerprint}`;
+  const tags = ["bug", "openloops", "loop-health", failure.classification];
+  const priority = failure.classification === "auth" || failure.classification === "rate_limit" ? "high" : "medium";
+  return {
+    title,
+    description,
+    priority,
+    tags,
+    dedupeKey,
+    search: { query: dedupeKey },
+    compatibilityFallback: {
+      search: ["todos", "search", dedupeKey, "--json"],
+      add: ["todos", "add", title, "--description", description, "--tag", tags.join(","), "--priority", priority],
+      comment: ["todos", "comment", "<task-id>", description]
+    },
+    futureNativeUpsert: {
+      command: "todos upsert",
+      fields: {
+        title,
+        description,
+        priority,
+        tags,
+        dedupeKey,
+        routeSource: route.source,
+        routeKind: route.kind,
+        routeLoopId: route.loopId,
+        routeLoopName: route.loopName
+      }
+    }
+  };
+}
+function expectationForLoop(store, loop) {
+  const latestRun = store.listRuns({ loopId: loop.id, limit: 1 })[0];
+  const route = targetRoute(loop);
+  if (!latestRun) {
+    return {
+      loop: { id: loop.id, name: loop.name, status: loop.status, nextRunAt: loop.nextRunAt },
+      ok: true,
+      check: { id: "latest-run-succeeded", status: "warn", message: "loop has no recorded runs yet" },
+      route
+    };
+  }
+  if (latestRun.status === "succeeded") {
+    return {
+      loop: { id: loop.id, name: loop.name, status: loop.status, nextRunAt: loop.nextRunAt },
+      ok: true,
+      check: { id: "latest-run-succeeded", status: "pass", message: "latest run succeeded" },
+      latestRun: healthRun(latestRun),
+      route
+    };
+  }
+  const failure = classifyRunFailure(latestRun);
+  return {
+    loop: { id: loop.id, name: loop.name, status: loop.status, nextRunAt: loop.nextRunAt },
+    ok: false,
+    check: { id: "latest-run-succeeded", status: "fail", message: `latest run is ${latestRun.status}` },
+    latestRun: healthRun(latestRun),
+    failure,
+    route,
+    recommendedTask: failure ? recommendedTask(loop, latestRun, failure, route) : undefined
+  };
+}
+function buildHealthReport(store, opts = {}) {
+  const loops2 = store.listLoops({ includeArchived: opts.includeArchived, limit: opts.limit ?? 200 });
+  const expectations = loops2.map((loop) => expectationForLoop(store, loop));
+  const classifications = Object.fromEntries(CLASSIFICATIONS.map((key) => [key, 0]));
+  for (const expectation of expectations) {
+    if (expectation.failure)
+      classifications[expectation.failure.classification] += 1;
+  }
+  const unhealthy = expectations.filter((expectation) => !expectation.ok).length;
+  const warnings = expectations.filter((expectation) => expectation.check.status === "warn").length;
+  return {
+    ok: unhealthy === 0,
+    generatedAt: new Date().toISOString(),
+    summary: {
+      loops: expectations.length,
+      healthy: expectations.length - unhealthy,
+      unhealthy,
+      warnings
+    },
+    classifications,
+    expectations
+  };
+}
 export {
   workflowExecutionOrder,
   workflowBodyFromJson,
@@ -4607,11 +4850,14 @@ export {
   isTerminal as isGoalTerminal,
   initialNextRun,
   getLoopTemplate,
+  expectationForLoop,
   executeWorkflow,
   executeTarget,
   executeLoopTarget,
   executeLoop,
   computeNextAfter,
+  classifyRunFailure,
+  buildHealthReport,
   TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID,
   Store,
   LoopsClient,

package/dist/lib/health.d.ts

@@ -0,0 +1,70 @@
+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 interface RunFailureSignal {
+    classification: RunFailureClassification;
+    fingerprint: string;
+    evidence: {
+        error?: string;
+        stdout?: string;
+        stderr?: string;
+        exitCode?: number;
+    };
+}
+export interface RecommendedTaskUpsert {
+    title: string;
+    description: string;
+    priority: "critical" | "high" | "medium" | "low";
+    tags: string[];
+    dedupeKey: string;
+    search: {
+        query: string;
+    };
+    compatibilityFallback: {
+        search: string[];
+        add: string[];
+        comment: string[];
+    };
+    futureNativeUpsert: {
+        command: string;
+        fields: Record<string, string | string[]>;
+    };
+}
+export interface LoopExpectationResult {
+    loop: Pick<Loop, "id" | "name" | "status" | "nextRunAt">;
+    ok: boolean;
+    check: {
+        id: "latest-run-succeeded";
+        status: "pass" | "fail" | "warn";
+        message: string;
+    };
+    latestRun?: LoopRun;
+    failure?: RunFailureSignal;
+    route: {
+        source: "openloops";
+        kind: "loop_expectation";
+        loopId: string;
+        loopName: string;
+        cwd?: string;
+        provider?: string;
+    };
+    recommendedTask?: RecommendedTaskUpsert;
+}
+export interface LoopsHealthReport {
+    ok: boolean;
+    generatedAt: string;
+    summary: {
+        loops: number;
+        healthy: number;
+        unhealthy: number;
+        warnings: number;
+    };
+    classifications: Record<RunFailureClassification, number>;
+    expectations: LoopExpectationResult[];
+}
+export declare function classifyRunFailure(run: LoopRun): RunFailureSignal | undefined;
+export declare function expectationForLoop(store: Store, loop: Loop): LoopExpectationResult;
+export declare function buildHealthReport(store: Store, opts?: {
+    includeArchived?: boolean;
+    limit?: number;
+}): LoopsHealthReport;

package/dist/lib/store.js

@@ -326,6 +326,17 @@ function optionalPositiveInteger(value, label) {
     throw new Error(`${label} must be a positive integer`);
   return value;
 }
+function optionalStringArray(value, label) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value))
+    throw new Error(`${label} must be an array`);
+  const values = value.map((entry, index) => {
+    assertString(entry, `${label}[${index}]`);
+    return entry.trim();
+  }).filter(Boolean);
+  return values.length ? values : undefined;
+}
 function normalizeGoalSpec(value, label = "goal") {
   if (value === undefined)
     return;
@@ -397,6 +408,14 @@ function validateTarget(value, label) {
         throw new Error(`${label}.sandbox is currently supported only for provider codewith, codex, or cursor`);
       }
     }
+    if (value.allowlist !== undefined) {
+      assertObject(value.allowlist, `${label}.allowlist`);
+      optionalStringArray(value.allowlist.tools, `${label}.allowlist.tools`);
+      optionalStringArray(value.allowlist.commands, `${label}.allowlist.commands`);
+      if (value.allowlist.enforcement !== undefined && value.allowlist.enforcement !== "metadata_only") {
+        throw new Error(`${label}.allowlist.enforcement must be metadata_only`);
+      }
+    }
     return value;
   }
   throw new Error(`${label}.type must be command or agent`);

package/dist/sdk/index.js

@@ -326,6 +326,17 @@ function optionalPositiveInteger(value, label) {
     throw new Error(`${label} must be a positive integer`);
   return value;
 }
+function optionalStringArray(value, label) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value))
+    throw new Error(`${label} must be an array`);
+  const values = value.map((entry, index) => {
+    assertString(entry, `${label}[${index}]`);
+    return entry.trim();
+  }).filter(Boolean);
+  return values.length ? values : undefined;
+}
 function normalizeGoalSpec(value, label = "goal") {
   if (value === undefined)
     return;
@@ -397,6 +408,14 @@ function validateTarget(value, label) {
         throw new Error(`${label}.sandbox is currently supported only for provider codewith, codex, or cursor`);
       }
     }
+    if (value.allowlist !== undefined) {
+      assertObject(value.allowlist, `${label}.allowlist`);
+      optionalStringArray(value.allowlist.tools, `${label}.allowlist.tools`);
+      optionalStringArray(value.allowlist.commands, `${label}.allowlist.commands`);
+      if (value.allowlist.enforcement !== undefined && value.allowlist.enforcement !== "metadata_only") {
+        throw new Error(`${label}.allowlist.enforcement must be metadata_only`);
+      }
+    }
     return value;
   }
   throw new Error(`${label}.type must be command or agent`);
@@ -2455,6 +2474,16 @@ function metadataEnv(metadata) {
     env.LOOPS_GOAL_NODE_KEY = metadata.goalNodeKey;
   return env;
 }
+function allowlistEnv(allowlist) {
+  const env = {};
+  if (allowlist?.tools?.length)
+    env.LOOPS_AGENT_ALLOWED_TOOLS = allowlist.tools.join(",");
+  if (allowlist?.commands?.length)
+    env.LOOPS_AGENT_ALLOWED_COMMANDS = allowlist.commands.join(",");
+  if (allowlist?.tools?.length || allowlist?.commands?.length)
+    env.LOOPS_AGENT_ALLOWLIST_ENFORCEMENT = "metadata_only";
+  return env;
+}
 function providerCommand(provider) {
   switch (provider) {
     case "claude":
@@ -2662,7 +2691,8 @@ function commandSpec(target) {
     account: agentTarget.account,
     accountTool: agentTarget.account?.tool ?? accountToolForProvider(agentTarget.provider),
     preflightAnyOf: agentTarget.provider === "cursor" ? ["cursor", "agent"] : undefined,
-    stdin: agentTarget.prompt
+    stdin: agentTarget.prompt,
+    allowlist: agentTarget.allowlist
   };
 }
 function executionEnv(spec, metadata, opts) {
@@ -2674,6 +2704,7 @@ function executionEnv(spec, metadata, opts) {
     Object.assign(env, accountEnv);
   }
   Object.assign(env, spec.env ?? {});
+  Object.assign(env, allowlistEnv(spec.allowlist));
   env.PATH = normalizeExecutionPath(env);
   Object.assign(env, metadataEnv(metadata));
   return env;
@@ -2712,6 +2743,9 @@ function remoteBootstrapLines(spec, metadata) {
       continue;
     lines.push(`export ${key}=${shellQuote(value)}`);
   }
+  for (const [key, value] of Object.entries(allowlistEnv(spec.allowlist))) {
+    lines.push(`export ${key}=${shellQuote(value)}`);
+  }
   return lines;
 }
 function remoteScript(spec, metadata) {

package/dist/types.d.ts

@@ -54,6 +54,11 @@ export type AgentProvider = "claude" | "cursor" | "codewith" | "aicopilot" | "op
 export type AgentConfigIsolation = "safe" | "none";
 export type AgentPermissionMode = "default" | "plan" | "auto" | "bypass";
 export type AgentSandbox = "read-only" | "workspace-write" | "danger-full-access" | "enabled" | "disabled";
+export interface AgentAllowlistSpec {
+    tools?: string[];
+    commands?: string[];
+    enforcement?: "metadata_only";
+}
 export interface AgentTarget {
     type: "agent";
     provider: AgentProvider;
@@ -68,6 +73,7 @@ export interface AgentTarget {
     configIsolation?: AgentConfigIsolation;
     permissionMode?: AgentPermissionMode;
     sandbox?: AgentSandbox;
+    allowlist?: AgentAllowlistSpec;
     account?: AccountRef;
 }
 export interface WorkflowTarget {

package/docs/USAGE.md

@@ -94,6 +94,23 @@ loops create agent supply-chain-watch \
   --prompt "Check for suspicious dependency or supply-chain changes. Report only concrete findings."
 ```
 
+Agent loops can also carry advisory per-session allowlist metadata:
+
+```bash
+loops create agent repo-check \
+  --provider codewith \
+  --every 15m \
+  --cwd /path/to/repo \
+  --prompt "Check the repo and report concrete failures." \
+  --allow-tool functions.exec_command \
+  --allow-command git,bun
+```
+
+These fields are stored on the loop target and exposed to the run environment
+as `LOOPS_AGENT_ALLOWED_TOOLS`, `LOOPS_AGENT_ALLOWED_COMMANDS`, and
+`LOOPS_AGENT_ALLOWLIST_ENFORCEMENT=metadata_only`. They are not enforced by
+OpenLoops yet; provider-native enforcement will be added separately.
+
 For `codewith` and `aicopilot` account isolation, register matching OpenAccounts tools first if they are not built in on the machine:
 
 ```bash
@@ -201,6 +218,14 @@ cat task-created-event.json | loops events handle todos-task \
   --sandbox danger-full-access
 ```
 
+Task routing is explicit opt-in. The handler skips the event without creating a
+workflow unless the event data or metadata has `route_enabled=true`,
+`automation.allowed=true`, or a task tag containing `auto:route`. It also skips
+blocked, completed/done, cancelled/canceled, failed, archived, manual,
+approval-required, or `no-auto` tasks. This guard exists even when the upstream
+`@hasna/events` webhook filter is misconfigured, so task existence alone is not
+permission to execute agent work.
+
 For other Hasna apps that expose `@hasna/events` webhooks, use the generic
 handler:
 
@@ -250,6 +275,27 @@ loops run-now <id-or-name>
 
 Use `--json` for machine-readable output. Prompt bodies and run stdout/stderr are redacted by default in status output. `loops run-now` exits non-zero when the recorded run fails or times out.
 
+## Health And Expectations
+
+`loops health --json` summarizes the latest run for each loop and classifies
+agent-run failures for default-loop SLOs:
+
+```bash
+loops health --json
+loops expectations <loop-id-or-name> --json
+```
+
+The JSON contains the expectation result, bounded error/stdout/stderr evidence,
+a stable failure fingerprint, route metadata, and recommended task fields.
+OpenLoops does not mutate Todos from these commands. Until Todos has a native
+upsert command, consumers can use the included compatibility fallback:
+`todos search <dedupe-key>`, then `todos add ...` or `todos comment ...`.
+The planned native integration is represented in `futureNativeUpsert`.
+
+Failure classifications are: `rate_limit`, `auth`, `model_not_found`,
+`context_length`, `schema_response_format`, `node_init`, `timeout`, `sigsegv`,
+`skipped_previous_active`, and `unknown`.
+
 Archive loops when retiring old automation but preserving history:
 
 ```bash

package/package.json

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