@hasna/loops 0.3.59 → 0.4.0

package/dist/test-helpers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared deadline-based polling and process-kill verification helpers for the
+ * test suite. Test-only: nothing in src/ production code may import this file.
+ */
+export interface WaitUntilOptions {
+    /** Total time to wait before failing (default 5s). */
+    timeoutMs?: number;
+    /** Poll interval (default 5ms). */
+    intervalMs?: number;
+    /** Included in the timeout error to identify the stuck condition. */
+    label?: string;
+}
+/**
+ * Poll `check` until it returns a truthy value, with a hard deadline.
+ * Returns the first truthy value; throws once the deadline passes so a stuck
+ * condition fails the test instead of silently falling through.
+ */
+export declare function waitUntil<T>(check: () => T | undefined | null | false | Promise<T | undefined | null | false>, opts?: WaitUntilOptions): Promise<T>;
+/**
+ * Shell command that blocks until `gate` exists, then writes `text` to
+ * `marker`. Replaces fixed `sleep N; printf ...` fixtures: the child stays
+ * alive (blocked on the gate) for exactly as long as the test needs, and a
+ * kill can be proven by opening the gate and observing that the marker never
+ * appears (see {@link expectMarkerNeverWritten}).
+ */
+export declare function gatedWriteCommand(gate: string, marker: string, opts?: {
+    text?: string;
+    append?: boolean;
+}): string;
+/** Open a {@link gatedWriteCommand} gate so a still-alive child can finish. */
+export declare function openGate(gate: string): void;
+/**
+ * Prove a gated child process was killed: open the gate and verify the marker
+ * still does not appear. A surviving child polls the gate every 20ms, so the
+ * default 250ms settle window gives it >10x the time it would need to write.
+ */
+export declare function expectMarkerNeverWritten(gate: string, marker: string, settleMs?: number): Promise<void>;

package/dist/types.d.ts

@@ -370,6 +370,8 @@ export interface LoopRun {
     claimedBy?: string;
     leaseExpiresAt?: string;
     pid?: number;
+    pgid?: number;
+    processStartedAt?: string;
     exitCode?: number;
     durationMs?: number;
     stdout?: string;

package/docs/USAGE.md

@@ -6,7 +6,7 @@ It supports deterministic command loops, JSON-defined workflows, and guarded CLI
 
 - `claude`
 - `agent` (Cursor Agent CLI)
-- `codewith exec`
+- `codewith agent start`
 - `aicopilot run`
 - `opencode run`
 - `codex exec`
@@ -313,6 +313,15 @@ Use `shell: true` only when you intentionally want shell parsing:
 { "type": "command", "command": "git status --short", "shell": true }
 ```
 
+Gate steps can end a workflow early without failing it. A step opts into
+blocked-exit semantics either explicitly via `"blockedExitCodes": [12]` on the
+step, or by naming convention: a step whose `id` or `name` contains "gate" as a
+standalone word (for example `gate`, `triage-gate`, `gate_check`) treats exit
+code 12 as "blocked" — the step and its dependents are recorded as skipped and
+the workflow still succeeds. Substring matches such as `gateway`, `aggregate`,
+or `delegate` do NOT inherit gate behavior; use `blockedExitCodes` explicitly
+for those. Set `"blockedExitCodes": []` on a gate-named step to opt out.
+
 ## Templates And Task Events
 
 Built-in templates turn common orchestration flows into reusable workflow JSON.
@@ -448,18 +457,21 @@ explicit break-glass handling for emergency workflows that need full access.
 
 Repo-mutating task/event routes should set `worktreeMode=required` so the
 workflow fails fast instead of falling back to the main checkout. When
-`projectPath` is an existing git repository, OpenLoops inserts a
-`prepare-worktree` command step before the worker and runs the worker/verifier
-from a deterministic worktree under `~/.hasna/loops/worktrees/<repo>/<run>`.
-The generated agent target includes worktree metadata (`mode`, `cwd`, `path`,
-`branch`, `originalCwd`) so dry-runs and workflow inspection expose the exact
-checkout.
-
-Before a worker starts, `prepare-worktree` verifies that any existing managed
-path is a real git worktree with the same top-level checkout, the same git
-common directory as the source repo, and the expected generated branch. A
-detached HEAD or unexpected branch fails closed with evidence instead of
-silently running a mutating workflow in the wrong state.
+`projectPath` is an existing git repository, the executor prepares and enters
+a deterministic worktree under `~/.hasna/loops/worktrees/<repo>/<run>` before
+spawning the worker/verifier — locally and on machine-assigned (remote) loops,
+where the dispatch script runs the equivalent `git worktree add`/reuse checks
+on the remote machine. The generated agent target includes worktree metadata
+(`mode`, `cwd`, `path`, `branch`, `originalCwd`) so dry-runs and workflow
+inspection expose the exact checkout.
+
+Before a worker starts, worktree preparation verifies that any existing
+managed path is a real git worktree with the same top-level checkout, the same
+git common directory as the source repo, and the expected generated branch. A
+detached HEAD or unexpected branch fails closed with evidence
+(`worktreeMode=required`) instead of silently running a mutating workflow in
+the wrong state; `worktreeMode=auto` falls back to the original checkout and
+records the fallback.
 
 Use explicit main/default checkout mode only when the task truly requires it:
 
@@ -785,8 +797,9 @@ record an `auto_route_skipped_reason`. Without `--auto-route`, route commands
 only upsert deduped tasks and do not launch agents.
 
 Failure classifications are: `rate_limit`, `auth`, `model_not_found`,
-`context_length`, `schema_response_format`, `node_init`, `timeout`, `sigsegv`,
-`skipped_previous_active`, and `unknown`.
+`context_length`, `schema_response_format`, `node_init`, `preflight`,
+`route_functional`, `timeout`, `sigsegv`, `skipped_previous_active`,
+`circuit_breaker`, and `unknown`.
 
 ## Hygiene
 
@@ -893,17 +906,26 @@ On Linux this writes a user systemd service. On macOS it writes a LaunchAgent pl
 The adapters intentionally use provider command surfaces instead of pretending every agent has one SDK:
 
 - Claude uses `claude -p --output-format json` and safe-mode/local setting sources by default.
-- Codewith uses `codewith --ask-for-approval never exec --json --ephemeral --skip-git-repo-check`, with `--add-dir` for explicit extra writable directories.
+- Codewith uses durable `codewith --ask-for-approval never agent start` background-agent runs by default, then polls `codewith agent read` until the run is terminal and records compact status/event evidence. Remote Codewith agent steps fail closed until remote durable readback is implemented, so workflows do not advance immediately after enqueue. OpenLoops rejects Codewith `extraArgs` that try to force `exec`, `--ephemeral`, or other non-durable exec-only flags for task-lifecycle, planner, worker, verifier, reviewer, release, or other long-running agentic work.
 - AI Copilot and OpenCode use `run --format json --pure`. OpenCode requires an explicit provider/model id because ambient OpenCode config is machine-specific.
 - Cursor is CLI-first for now via the standalone `agent -p` binary. OpenLoops no longer falls back to `cursor agent`; install the standalone Cursor Agent CLI so preflight and scheduled runs use the same executable.
 - Codex uses `codex --ask-for-approval never exec --json --ephemeral --skip-git-repo-check`, with `--add-dir` for explicit extra writable directories where supported.
-- Agent prompts are sent through child stdin instead of argv so prompt bodies do not appear in process listings.
+- Agent prompts are sent through child stdin instead of argv where the provider supports stdin. Codewith durable background agents currently accept prompts as native `agent start` arguments, so OpenLoops stores only bounded status/event evidence and omits raw Codewith event payloads from workflow stdout.
 - When `--account` or a step `account` is set, OpenLoops resolves `accounts env <profile> --tool <tool>` before spawning the target, strips inherited tool home/API-key variables, and applies the selected profile only to that process. Missing account profiles fail before the provider binary receives the prompt.
-- `--auth-profile` and step `authProfile` are provider-native auth selectors. They currently apply to Codewith and are passed to Codewith as `--auth-profile <name>` before `exec`; they do not call OpenAccounts.
+- `--auth-profile` and step `authProfile` are provider-native auth selectors. They currently apply to Codewith and are passed to Codewith as `--auth-profile <name>` before `agent start/read/logs`; they do not call OpenAccounts.
 - `--sandbox` maps to provider-native sandbox flags. Codewith/Codex accept `read-only`, `workspace-write`, or `danger-full-access`; Cursor accepts `enabled` or `disabled`.
 - `--permission-mode` maps `plan`, `auto`, and `bypass` where the provider supports it. Claude uses native permission modes, Cursor maps bypass to `--force`, and OpenCode/AICopilot map bypass to `--dangerously-skip-permissions`.
 - `--variant` is provider-specific reasoning/model effort. Claude maps it to `--effort`, Codewith/Codex map it to `model_reasoning_effort`, and OpenCode/AICopilot pass `--variant`.
 - Daemon and scheduled runs prepend common user executable directories such as `~/.local/bin` and `~/.bun/bin` before resolving provider CLIs.
+- Agent targets that set neither `timeoutMs` nor `idleTimeoutMs` get a default
+  idle watchdog: 30 minutes without stdout/stderr for streaming providers
+  (codex, cursor), and 4 hours for providers whose CLIs buffer all output until
+  completion (claude, opencode, aicopilot) or whose durable progress
+  fingerprint can stay flat during long work (codewith). Override the default
+  with `LOOPS_AGENT_IDLE_TIMEOUT_MS=<ms>`, disable it with
+  `LOOPS_AGENT_IDLE_TIMEOUT_MS=0` (or `none`/`off`), or set explicit
+  `timeoutMs`/`idleTimeoutMs` per target — `"timeoutMs": null` opts a target
+  out of both the wall-clock default and the idle watchdog.
 
 For production loops that can mutate repos, prefer the built-in
 `worktreeMode=auto`/`required` path and explicit prompts that name allowed write

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.3.59",
+  "version": "0.4.0",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",
@@ -31,6 +31,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "docs",
     "LICENSE"
   ],
@@ -39,7 +40,7 @@
     "build:bin": "bun build src/cli/index.ts --compile --outfile dist/loops",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "prepare": "bun run build",
+    "prepare": "test -d dist || bun run build",
     "dev:cli": "bun run src/cli/index.ts",
     "dev:daemon": "bun run src/daemon/index.ts",
     "prepublishOnly": "bun run build"
@@ -70,13 +71,15 @@
   },
   "dependencies": {
     "@hasna/events": "^0.1.9",
-    "@hasna/machines": "0.0.49",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openrouter/ai-sdk-provider": "2.9.1",
     "ai": "6.0.204",
     "commander": "^13.1.0",
     "zod": "4.4.3"
   },
+  "optionalDependencies": {
+    "@hasna/machines": "0.0.49"
+  },
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^5.7.3"