@hasna/loops 0.3.15 → 0.3.17

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/hygiene.d.ts

@@ -0,0 +1,62 @@
+import type { Loop } from "../types.js";
+import type { Store } from "./store.js";
+export interface NameHygieneChange {
+    id: string;
+    status: string;
+    scope: "machine" | "repo";
+    scopeSlug: string;
+    oldName: string;
+    newName: string;
+    changed: boolean;
+}
+export interface NameHygieneReport {
+    ok: boolean;
+    generatedAt: string;
+    applied: boolean;
+    checked: number;
+    changed: number;
+    changes: NameHygieneChange[];
+}
+export interface DuplicateOverlapGroup {
+    key: string;
+    baseName: string;
+    cwd?: string;
+    schedule: string;
+    loops: Array<Pick<Loop, "id" | "name" | "status" | "nextRunAt">>;
+}
+export interface DuplicateOverlapReport {
+    ok: boolean;
+    generatedAt: string;
+    checked: number;
+    groups: DuplicateOverlapGroup[];
+}
+export interface ScriptBackedLoop {
+    id: string;
+    name: string;
+    status: string;
+    cwd?: string;
+    command: string;
+    scriptMatches: string[];
+}
+export interface ScriptInventoryReport {
+    ok: boolean;
+    generatedAt: string;
+    checked: number;
+    scriptBacked: number;
+    loops: ScriptBackedLoop[];
+}
+export declare function buildNameHygieneReport(store: Store, opts?: {
+    apply?: boolean;
+    includeStopped?: boolean;
+    includeInactive?: boolean;
+    limit?: number;
+}): NameHygieneReport;
+export declare function buildDuplicateOverlapReport(store: Store, opts?: {
+    includeInactive?: boolean;
+    limit?: number;
+}): DuplicateOverlapReport;
+export declare function buildScriptInventoryReport(store: Store, opts?: {
+    scriptsDir?: string;
+    includeInactive?: boolean;
+    limit?: number;
+}): ScriptInventoryReport;

package/dist/lib/store.d.ts

@@ -79,6 +79,7 @@ export declare class Store {
     }): Loop[];
     dueLoops(now: Date): Loop[];
     updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt">>, opts?: DaemonLeaseFence): Loop;
+    renameLoop(id: string, name: string, opts?: DaemonLeaseFence): Loop;
     archiveLoop(idOrName: string): Loop;
     unarchiveLoop(idOrName: string): Loop;
     deleteLoop(idOrName: string): boolean;

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`);
@@ -1031,6 +1050,30 @@ class Store {
       throw new Error(`loop not found after update: ${id}`);
     return after;
   }
+  renameLoop(id, name, opts = {}) {
+    const current = this.getLoop(id);
+    if (!current)
+      throw new Error(`loop not found: ${id}`);
+    const trimmed = name.trim();
+    if (!trimmed)
+      throw new Error("loop name must not be empty");
+    const updated = (opts.now ?? new Date).toISOString();
+    this.db.query(`UPDATE loops SET name=$name, updated_at=$updated
+         WHERE id=$id
+           AND ($daemonLeaseId IS NULL OR EXISTS (
+             SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
+           ))`).run({
+      $id: id,
+      $name: trimmed,
+      $updated: updated,
+      $daemonLeaseId: opts.daemonLeaseId ?? null,
+      $now: updated
+    });
+    const after = this.getLoop(id);
+    if (!after)
+      throw new Error(`loop not found after rename: ${id}`);
+    return after;
+  }
   archiveLoop(idOrName) {
     const loop = this.requireLoop(idOrName);
     if (loop.archivedAt)

package/dist/lib/templates.d.ts

@@ -1,6 +1,7 @@
 import type { AccountRef, AgentPermissionMode, AgentProvider, AgentSandbox, CreateWorkflowInput, LoopTemplateSummary } from "../types.js";
 export declare const TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID = "todos-task-worker-verifier";
 export declare const EVENT_WORKER_VERIFIER_TEMPLATE_ID = "event-worker-verifier";
+export declare const BOUNDED_AGENT_WORKER_VERIFIER_TEMPLATE_ID = "bounded-agent-worker-verifier";
 export interface TodosTaskWorkflowTemplateInput {
     taskId: string;
     taskTitle?: string;
@@ -46,8 +47,30 @@ export interface EventWorkflowTemplateInput {
     permissionMode?: AgentPermissionMode;
     sandbox?: AgentSandbox;
 }
+export interface BoundedAgentWorkflowTemplateInput {
+    name?: string;
+    objective: string;
+    prompt?: string;
+    projectPath: string;
+    provider?: AgentProvider;
+    authProfile?: string;
+    authProfilePool?: string[];
+    workerAuthProfile?: string;
+    verifierAuthProfile?: string;
+    account?: AccountRef;
+    accountPool?: AccountRef[];
+    workerAccount?: AccountRef;
+    verifierAccount?: AccountRef;
+    model?: string;
+    variant?: string;
+    agent?: string;
+    permissionMode?: AgentPermissionMode;
+    sandbox?: AgentSandbox;
+    timeoutMs?: number;
+}
 export declare function listLoopTemplates(): LoopTemplateSummary[];
 export declare function getLoopTemplate(id: string): LoopTemplateSummary | undefined;
 export declare function renderTodosTaskWorkerVerifierWorkflow(input: TodosTaskWorkflowTemplateInput): CreateWorkflowInput;
 export declare function renderEventWorkerVerifierWorkflow(input: EventWorkflowTemplateInput): CreateWorkflowInput;
+export declare function renderBoundedAgentWorkerVerifierWorkflow(input: BoundedAgentWorkflowTemplateInput): CreateWorkflowInput;
 export declare function renderLoopTemplate(id: string, values: Record<string, string | undefined>): CreateWorkflowInput;

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`);
@@ -1031,6 +1050,30 @@ class Store {
       throw new Error(`loop not found after update: ${id}`);
     return after;
   }
+  renameLoop(id, name, opts = {}) {
+    const current = this.getLoop(id);
+    if (!current)
+      throw new Error(`loop not found: ${id}`);
+    const trimmed = name.trim();
+    if (!trimmed)
+      throw new Error("loop name must not be empty");
+    const updated = (opts.now ?? new Date).toISOString();
+    this.db.query(`UPDATE loops SET name=$name, updated_at=$updated
+         WHERE id=$id
+           AND ($daemonLeaseId IS NULL OR EXISTS (
+             SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
+           ))`).run({
+      $id: id,
+      $name: trimmed,
+      $updated: updated,
+      $daemonLeaseId: opts.daemonLeaseId ?? null,
+      $now: updated
+    });
+    const after = this.getLoop(id);
+    if (!after)
+      throw new Error(`loop not found after rename: ${id}`);
+    return after;
+  }
   archiveLoop(idOrName) {
     const loop = this.requireLoop(idOrName);
     if (loop.archivedAt)
@@ -2455,6 +2498,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 +2715,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 +2728,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 +2767,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
@@ -167,7 +184,8 @@ Use `shell: true` only when you intentionally want shell parsing:
 Built-in templates turn common orchestration flows into reusable workflow JSON.
 `todos-task-worker-verifier` performs one todos task and then verifies it.
 `event-worker-verifier` handles any Hasna event envelope and then verifies the
-handling.
+handling. `bounded-agent-worker-verifier` is for recurring bounded agent work:
+one worker runs a narrow objective, then a fresh verifier audits the result.
 
 ```bash
 loops templates list
@@ -187,6 +205,12 @@ loops templates render event-worker-verifier \
   --var eventSource=knowledge \
   --var eventJson='{"id":"<event-id>"}' \
   --var projectPath=/path/to/repo
+loops templates render bounded-agent-worker-verifier \
+  --var objective="Check docs drift and queue tasks for gaps" \
+  --var projectPath=/path/to/repo \
+  --var provider=codewith \
+  --var authProfilePool=account004,account005 \
+  --var sandbox=danger-full-access
 ```
 
 For event-driven task automation, `loops events handle todos-task` reads a
@@ -201,6 +225,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 +282,54 @@ 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 `health` or `expectations`. To turn failed
+expectations into deduped tasks, use the explicit routing command:
+
+```bash
+loops health route-tasks \
+  --project ~/.hasna/loops \
+  --task-list loop-error-self-heal \
+  --max-actions 5
+```
+
+Use `--dry-run --json` first when testing a new automation path. Routed tasks
+include the stable failure fingerprint, classification, loop id/name, and
+`no_tmux_dispatch=true` metadata.
+
+Failure classifications are: `rate_limit`, `auth`, `model_not_found`,
+`context_length`, `schema_response_format`, `node_init`, `timeout`, `sigsegv`,
+`skipped_previous_active`, and `unknown`.
+
+## Hygiene
+
+OpenLoops includes deterministic hygiene checks for replacing local maintenance
+scripts with package commands:
+
+```bash
+loops hygiene names --json
+loops hygiene names --apply
+loops hygiene duplicates --json
+loops hygiene scripts --json
+```
+
+`hygiene names` reports canonical `machine-*` or `repo-<name>-*` loop names and
+only renames when `--apply` is present. `hygiene duplicates` groups loops with
+the same normalized name, cwd, and schedule. `hygiene scripts` inventories loops
+whose command still references `~/.hasna/loops/scripts`; use it as a migration
+gate before deleting local scripts.
+
 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.17",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",