oh-my-harness 0.18.0 → 0.19.0

package/README.md

@@ -103,12 +103,16 @@ your-project/
 │   │   ├── catalog-command-guard.sh   # Blocks dangerous commands
 │   │   ├── catalog-lint-on-save.sh    # Auto-lint on save
 │   │   └── catalog-auto-pr.sh         # Auto-create PR after push
+│   ├── loop/
+│   │   └── worktree/                  # gitignored — the loop's isolated git worktree (see Loop Engine)
 │   ├── state/                         # gitignored — log/runtime data
 │   │   ├── events.jsonl               # Unified hook event log (powers omh stats)
+│   │   ├── loop/                      # run.json (lock + identity), stop flag, runs/<id>/events.jsonl
 │   │   └── tdd-edits.json             # TDD guard working state
 │   └── manifest.json                  # Generated-files manifest
 ├── .claude/
 │   ├── settings.json                  # Claude permissions + hooks → .omh/hooks/*.sh
+│   ├── skills/omh-loop/SKILL.md       # "run this as a loop" skill
 │   └── oh-my-harness.json             # Harness init/sync state
 └── .codex/
     ├── config.toml                    # [features] hooks = true, goals = true
@@ -215,6 +219,7 @@ All enforcement is powered by **catalog blocks** — reusable, parameterized hoo
 | 🗜️ `compact-context` | maintenance | Re-injects context on session start |
 | 📋 `config-audit` | audit | Audit trail for config changes |
 | 🔔 `desktop-notify` | ux | Cross-platform desktop notifications |
+| 🔁 `loop-guard` | quality | Blocks a loop session from writing its own work orders or touching architect-only paths |
 
 ### Usage in `harness.yaml`
 
@@ -261,6 +266,96 @@ on a non-blocking block (e.g. `lint-on-save`) is reported and ignored.
 
 ---
 
+## 🔁 Autonomous Loop Engine
+
+Once `omh init`/`omh sync` has run (with `loop.enabled: true`, the default),
+any agent session (Claude Code, Codex, Pi) can be told **"run this as a loop"** — the generated `omh-loop` skill turns that
+into a fully set-up autonomous loop, no manual wiring:
+
+```text
+you: "ship the remaining Phase B tasks as a loop"
+        │
+        ▼  omh-loop skill (the session becomes the ARCHITECT)
+  1. writes the `loop.ledger`     — default WORKPLAN.md; goal gates + task checkboxes
+  2. writes `loop.workOrders`/*.md — default docs/work-orders; one exact work order per task
+  3. runs `omh loop start`        — a detached supervisor; with `isolate: true` (default), in its own git worktree
+  4. attaches monitoring          — omh loop status, then tail -f .omh/state/loop/runs/<id>/events.jsonl
+        │
+        ▼  loop (fresh headless session per iteration, cheap model)
+  pick next unchecked task → implement its work order exactly → run its
+  acceptance commands → tick checkbox + commit → repeat until the sentinel
+```
+
+The design follows a battle-tested pattern from real autonomous runs: state
+lives in **files** (ledger + git log), never in a conversation. Each iteration
+is a fresh headless session (`claude -p` / `codex exec --dangerously-bypass-hook-trust` / `pi --print --no-session`)
+on an explicit cheap model, so token use stays flat.
+
+### Why it doesn't fall over
+
+Every guard below exists because the failure actually happened somewhere:
+
+| Guard | Failure it prevents |
+|-------|---------------------|
+| Sentinel = fixed string, whole line, clean exit only | a crashed turn (or a turn merely *mentioning* the sentinel) ending the loop as "complete" |
+| Three **separate** backoffs — usage limit / empty-output failed turn / consecutive `BLOCKED` | a loop once spun **266 iterations** doing nothing because waiting-on-a-human was treated like a failure |
+| `loop-guard` hook blocks the loop writing its own work orders (Edit/Write **and** Bash redirection/`cd`) | self-approval: the loop authoring the spec it then implements |
+| `loop-guard` blocks architect-only paths, listed **by name** | an abstract "don't improvise" is ignored; a named path is obeyed |
+| Worktree isolation (`isolate: true`, default) | the loop and the architect fighting over the same working tree |
+| Ledger seeded once, re-seeded only when the main-tree copy is newer | the loop's progress being rolled back — or a second goal reusing the first goal's ledger |
+
+### Configuration
+
+On by default. Everything is optional in `harness.yaml`:
+
+```yaml
+loop:
+  enabled: true                # false removes all loop assets on next sync
+  ledger: WORKPLAN.md          # single source of truth
+  workOrders: docs/work-orders # architect-written task specs
+  model: sonnet                # cheap implementation model (always explicit)
+  sentinel: OMH_GOAL_COMPLETE  # whole-line completion signal
+  interval: 120                # seconds between iterations
+  blockedBackoff: 1800         # backoff once stallStreak blocked/idle turns pile up
+  limitBackoff: 1800           # backoff after a provider usage limit
+  emptyBackoff: 300            # backoff after a crashed (empty-output / timed-out) turn
+  stallStreak: 3               # consecutive blocked/idle turns before blockedBackoff
+  turnTimeout: 7200            # hard per-turn timeout (seconds); the turn is killed past this
+  architectOnly: []            # paths the loop must never touch (name them!)
+  isolate: true                # run in .omh/loop/worktree on branch omh-loop
+  runtime: claude              # claude | codex | pi
+```
+
+### Operating it
+
+```bash
+omh loop start            # preflight, then a detached supervisor (the skill does this for you)
+omh loop status           # run id, pid, iteration, last event, events path
+tail -f .omh/state/loop/runs/<id>/events.jsonl   # progress / blocked / idle / limit / crash
+omh loop stop [--now]     # stop flag + SIGTERM to the whole process group (--now: 1s grace)
+omh loop clean [--branch] # remove the worktree and stale state (and optionally the omh-loop branch)
+```
+
+The supervisor is TypeScript (`src/loop/`), not a generated script: the runtime
+is spawned from an argv array (no shell), each turn is judged by the **ledger
+diff and git HEAD** rather than by grepping output, and the run lock is a single
+`run.json` created atomically with `link(2)`. POSIX only — it relies on process
+groups and `ps` for identity checks.
+
+Known limit: the ledger is seeded into the worktree once per goal (by content
+hash). Editing the main-tree ledger mid-run does nothing until the next start,
+which then re-seeds it — add mid-run tasks as new work orders instead, and edit
+the worktree's ledger if you must.
+
+A task the loop cannot finish (needs a human, or 3 failed attempts) is marked
+`BLOCKED: <reason>` in the ledger and skipped — the loop never idles waiting
+for a person. When you unblock it (e.g. fix an architect-only file), the loop
+picks it back up after its backoff. When the goal completes in isolation, merge
+the `omh-loop` branch and **re-verify** — a clean textual merge is not a
+semantic one.
+
+---
+
 ## 🖥️ Commands
 
 ```bash
@@ -403,13 +498,13 @@ oh-my-harness/
 ├── bin/                    # CLI entry point
 ├── src/
 │   ├── catalog/
-│   │   ├── blocks/         # 17 building block definitions
+│   │   ├── blocks/         # 18 building block definitions
 │   │   ├── types.ts        # BuildingBlock, HookEntry schemas
 │   │   ├── registry.ts     # Block discovery & search
 │   │   ├── template-engine.ts # Handlebars rendering + applyDefaults
 │   │   └── converter.ts    # HookEntry[] → rendered scripts
 │   ├── cli/
-│   │   ├── commands/       # init, doctor, catalog, hook, sync, test
+│   │   ├── commands/       # init, doctor, catalog, hook, sync, test, loop (start/run/stop/status/clean)
 │   │   ├── stats/          # TUI dashboard (ink/React)
 │   │   │   ├── App.tsx     # App shell (tab bar, keyboard nav)
 │   │   │   ├── data.ts     # Data aggregation layer
@@ -420,6 +515,14 @@ oh-my-harness/
 │   │   ├── tui/               # Interactive provider & model selection
 │   │   ├── provider-setup.ts  # Provider configuration UI
 │   │   └── tool-checker.ts    # Command executable checks
+│   ├── loop/               # autonomous loop supervisor (TypeScript, no generated shell)
+│   │   ├── supervisor.ts   # one run: lock → worktree/seed → turns → release
+│   │   ├── state.ts        # run.json link-lock, events, atomic writes
+│   │   ├── classify.ts     # turn verdict from ledger diff + HEAD; wait policy
+│   │   ├── runtime.ts      # argv per runtime, turn execution in its own process group
+│   │   ├── worktree.ts     # git worktree lifecycle, asset sync, ledger seeding
+│   │   ├── protocol.ts     # the rules, rendered into prompt / CLAUDE.md / skill
+│   │   └── stop.ts         # identity-checked group stop, group sweep
 │   ├── core/
 │   │   ├── harness-schema.ts      # harness.yaml Zod schema
 │   │   ├── merged-config.ts       # MergedConfig + HooksConfig interfaces
@@ -466,7 +569,7 @@ oh-my-harness/
 
 - [x] `npx oh-my-harness` — zero-install usage
 - [x] `omh sync` — regenerate from harness.yaml
-- [x] Building block catalog — 17 verified hook templates
+- [x] Building block catalog — 18 verified hook templates
 - [x] Project detector — 14 language auto-detection
 - [x] `omh test` — dry-run hook verification
 - [x] `omh stats` — TUI analytics dashboard (ink)
@@ -481,6 +584,7 @@ oh-my-harness/
 - [x] `ask` mode — request approval before executing risky tools (Claude native prompt / Pi `ctx.ui.select`; Codex falls back to block)
 - [x] `omh uninstall` — remove generated artifacts while preserving user content
 - [x] `omh config` — view, reconfigure, or reset the saved AI provider (rotate expired keys, switch provider/model)
+- [x] Autonomous loop engine — `omh-loop` skill, worktree-isolated runner, loop-guard, JSONL monitoring
 - [ ] Community harness.yaml registry — share and reuse configs
 - [ ] `omh modify "change X"` — NL config editing
 

package/dist/catalog/blocks/index.js

@@ -15,6 +15,7 @@ import { desktopNotify } from "./desktop-notify.js";
 import { configAudit } from "./config-audit.js";
 import { compactContext } from "./compact-context.js";
 import { worktreeSetup } from "./worktree-setup.js";
+import { loopGuard } from "./loop-guard.js";
 export const builtinBlocks = [
     branchGuard,
     commitTestGate,
@@ -33,4 +34,5 @@ export const builtinBlocks = [
     configAudit,
     compactContext,
     worktreeSetup,
+    loopGuard,
 ];

package/dist/catalog/blocks/loop-guard.d.ts

@@ -0,0 +1,10 @@
+import type { BuildingBlock } from "../types.js";
+/**
+ * Enforces the loop protocol's two deterministic bans as hard blocks instead
+ * of prose. Both have been violated in practice when they lived only in a
+ * ledger: a loop that writes its own work order and then implements it is
+ * approving itself, and architect-only files are exactly the ones a loop
+ * mis-diagnoses. Fires only in loop sessions — the runner exports OMH_LOOP=1,
+ * so the architect's own session is never blocked.
+ */
+export declare const loopGuard: BuildingBlock;

package/dist/catalog/blocks/loop-guard.js

@@ -0,0 +1,120 @@
+/**
+ * Enforces the loop protocol's two deterministic bans as hard blocks instead
+ * of prose. Both have been violated in practice when they lived only in a
+ * ledger: a loop that writes its own work order and then implements it is
+ * approving itself, and architect-only files are exactly the ones a loop
+ * mis-diagnoses. Fires only in loop sessions — the runner exports OMH_LOOP=1,
+ * so the architect's own session is never blocked.
+ */
+export const loopGuard = {
+    id: "loop-guard",
+    name: "Loop Guard",
+    description: "Blocks a loop session from writing its own work orders or touching architect-only paths",
+    category: "quality",
+    event: "PreToolUse",
+    matcher: "Edit|Write|Bash",
+    canBlock: true,
+    params: [
+        {
+            name: "workOrders",
+            type: "string",
+            description: "Work-order directory the loop must never write into",
+            required: false,
+            default: "docs/work-orders",
+        },
+        {
+            name: "architectOnly",
+            type: "string[]",
+            description: "Path prefixes only the architect may edit",
+            required: false,
+            default: [],
+        },
+    ],
+    template: `#!/bin/bash
+set -euo pipefail
+INPUT=$(cat)
+
+# Architect sessions pass through untouched; only the runner exports this.
+[[ "\${OMH_LOOP:-}" != "1" ]] && exit 0
+
+TOOL_NAME=$(echo "\$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE_PATH=$(echo "\$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+COMMAND=$(echo "\$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+# Codex apply_patch ships the whole patch in tool_input.command and names the
+# files in "*** {Add|Update|Delete} File: <path>" headers. Collect those
+# paths and treat them like file_path; the Bash write heuristic must NOT run
+# over patch text (it would fire on words inside the diff).
+PATCH_PATHS=()
+if [[ "\$TOOL_NAME" == "apply_patch" && -n "\$COMMAND" ]]; then
+  while IFS= read -r _p; do
+    _p="\${_p%$'\\r'}"
+    [[ -n "\$_p" ]] && PATCH_PATHS+=("\$_p")
+  done < <(printf '%s\\n' "\$COMMAND" | sed -nE 's/^\\*\\*\\* ((Add|Update|Delete) File|Move to): (.+)$/\\3/p')
+  COMMAND=""
+fi
+[[ -z "\$FILE_PATH" && -z "\$COMMAND" && \${#PATCH_PATHS[@]} -eq 0 ]] && exit 0
+
+# Component-boundary matching: wrap both sides in slashes so 'ios' matches
+# ios/App.swift and /repo/ios/... but never src/kiosk.ts.
+_omh_path_under() {
+  local file="/\$1/" prefix="\${2%/}"
+  [[ "\$file" == *"/\$prefix/"* ]]
+}
+
+# Bash coverage: a shell command that mentions a protected path AND carries a
+# write indicator is blocked. Reads (cat/grep of a work order) pass.
+# ponytail: substring heuristic — a command writing elsewhere while merely
+# mentioning a protected path is over-blocked; tighten to arg-level parsing if
+# that ever bites. This guards a drifting loop, not a malicious one — evasion
+# via split cd chains, variable indirection, pushd, or symlinks is explicitly
+# out of scope: winning that arms race needs a filesystem sandbox, not a hook.
+_omh_bash_writes_to() {
+  local cmd="\$1" target="\${2%/}"
+  [[ -z "\$cmd" || -z "\$target" ]] && return 1
+  [[ "\$cmd" == *"\$target"* ]] || return 1
+  # The path is interpolated into an ERE below: escape its metacharacters so
+  # "docs/[orders" cannot break the pattern (grep error = silent bypass) and
+  # "docs/o+rders" is compared literally.
+  target=$(printf '%s' "\$target" | sed -e 's/[][\\.*^$(){}?+|]/\\\\&/g')
+  local WRITE_OPS='(tee|mv|cp|rm|touch|truncate|sed[[:space:]]+-i[^[:space:]]*)'
+  # write op targeting the protected path directly ...
+  echo "\$cmd" | grep -qE '(>|>>)[[:space:]]*[^|&;]*'"\$target"'|(^|[^[:alnum:]_])'"\$WRITE_OPS"'[[:space:]][^|&;]*'"\$target" && return 0
+  # ... or a cd into it followed by any write op (relative paths escape the
+  # direct pattern once the cwd is inside the protected directory)
+  echo "\$cmd" | grep -qE '(^|[^[:alnum:]_])cd[[:space:]][^|&;]*'"\$target" \\
+    && echo "\$cmd" | grep -qE '>|(^|[^[:alnum:]_])'"\$WRITE_OPS"'[[:space:]]' 
+}
+
+# Any path a tool call names: the direct file_path plus apply_patch headers.
+_omh_any_path_under() {
+  local prefix="\$1" f
+  [[ -n "\$FILE_PATH" ]] && _omh_path_under "\$FILE_PATH" "\$prefix" && return 0
+  for f in "\${PATCH_PATHS[@]+"\${PATCH_PATHS[@]}"}"; do
+    _omh_path_under "\$f" "\$prefix" && return 0
+  done
+  return 1
+}
+
+WORK_ORDERS='{{{workOrders}}}'
+if _omh_any_path_under "\$WORK_ORDERS" || _omh_bash_writes_to "\$COMMAND" "\$WORK_ORDERS"; then
+  REASON="oh-my-harness: loop-guard — the loop must not write its own work orders. Mark the task 'BLOCKED: no work order' and move on; the architect writes work orders."
+  _log_event "block" "\$REASON"
+  _emit_decision "block" "\$REASON"
+  exit 0
+fi
+
+ARCHITECT_ONLY=({{#each architectOnly}}"{{{this}}}" {{/each}})
+for prefix in "\${ARCHITECT_ONLY[@]+"\${ARCHITECT_ONLY[@]}"}"; do
+  [[ -z "\$prefix" ]] && continue
+  if _omh_any_path_under "\$prefix" || _omh_bash_writes_to "\$COMMAND" "\$prefix"; then
+    REASON="oh-my-harness: loop-guard — \$prefix is architect-only. Mark the task 'BLOCKED: architect-only path' and move on."
+    _log_event "block" "\$REASON"
+    _emit_decision "block" "\$REASON"
+    exit 0
+  fi
+done
+
+exit 0`,
+    tags: ["loop", "autonomous", "quality", "guardrail"],
+};

package/dist/cli/commands/loop.d.ts

@@ -0,0 +1,54 @@
+import type { LoopConfig } from "../../core/merged-config.js";
+import type { LivenessDeps } from "../../loop/state.js";
+import { stopLoop } from "../../loop/stop.js";
+import type { SupervisorExit } from "../../loop/supervisor.js";
+/**
+ * `omh loop` — the user-facing (and skill-facing) entry points to the
+ * supervisor in src/loop. `start` launches `run` detached; everything else
+ * reads or signals the state that `run` maintains.
+ */
+export interface LoopResult {
+    exitCode: number;
+}
+/** The subset of ChildProcess that start relies on; injectable for tests. */
+export interface ChildLike {
+    pid?: number;
+    exitCode: number | null;
+    unref(): void;
+    once(event: "exit", cb: (code: number | null) => void): unknown;
+}
+export type SpawnLike = (cmd: string, args: string[], opts: Record<string, unknown>) => ChildLike;
+export interface LoopStartOptions extends LivenessDeps {
+    projectDir?: string;
+    spawnImpl?: SpawnLike;
+    platform?: NodeJS.Platform;
+    /** How long to wait for the supervisor to acquire the run. */
+    acquireTimeoutMs?: number;
+}
+export declare function loopStartCommand(options?: LoopStartOptions): Promise<LoopResult>;
+export interface LoopRunOptions {
+    projectDir?: string;
+    runId: string;
+    supervisorImpl?: (o: {
+        projectDir: string;
+        cfg: LoopConfig;
+        runId: string;
+    }) => Promise<SupervisorExit>;
+    sweepImpl?: () => void;
+}
+export declare function loopRunCommand(options: LoopRunOptions): Promise<LoopResult>;
+export interface LoopStopOptions {
+    projectDir?: string;
+    now?: boolean;
+    stopImpl?: typeof stopLoop;
+}
+export declare function loopStopCommand(options?: LoopStopOptions): Promise<LoopResult>;
+export interface LoopStatusOptions extends LivenessDeps {
+    projectDir?: string;
+}
+export declare function loopStatusCommand(options?: LoopStatusOptions): Promise<LoopResult>;
+export interface LoopCleanOptions {
+    projectDir?: string;
+    branch?: boolean;
+}
+export declare function loopCleanCommand(options?: LoopCleanOptions): Promise<LoopResult>;

package/dist/cli/commands/loop.js

@@ -0,0 +1,221 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import yaml from "js-yaml";
+import chalk from "chalk";
+import { HarnessConfigSchema } from "../../core/harness-schema.js";
+import { loopPaths, readRun, isRunLive, pruneRuns, runDir, readEvents } from "../../loop/state.js";
+import { stopLoop, sweepOwnGroup, isOurTurnGroup } from "../../loop/stop.js";
+import { runSupervisor } from "../../loop/supervisor.js";
+import { currentBranch, git, removeWorktree, WorktreeError } from "../../loop/worktree.js";
+const fail = (msg) => {
+    console.error(chalk.red(`omh loop: ${msg}`));
+    return { exitCode: 1 };
+};
+async function loadLoopConfig(projectDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(projectDir, "harness.yaml"), "utf-8");
+    }
+    catch {
+        return fail("harness.yaml not found — run `omh init` first");
+    }
+    const parsed = HarnessConfigSchema.safeParse(yaml.load(raw));
+    if (!parsed.success)
+        return fail(`harness.yaml is invalid: ${parsed.error.issues[0]?.message ?? "schema error"}`);
+    const loop = parsed.data.loop;
+    if (!loop || !loop.enabled)
+        return fail("the loop is disabled in harness.yaml (loop.enabled: false)");
+    return loop;
+}
+const isResult = (v) => typeof v === "object" && v !== null && "exitCode" in v;
+function newRunId(now = new Date()) {
+    const pad = (n) => String(n).padStart(2, "0");
+    const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-` +
+        `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    return `${stamp}-${randomBytes(2).toString("hex")}`;
+}
+export async function loopStartCommand(options = {}) {
+    const projectDir = path.resolve(options.projectDir ?? process.cwd());
+    const platform = options.platform ?? process.platform;
+    if (platform === "win32")
+        return fail("the loop is POSIX-only (process groups and ps are required)");
+    try {
+        await git(projectDir, ["rev-parse", "--show-toplevel"]);
+    }
+    catch {
+        return fail("not a git repository");
+    }
+    const cfg = await loadLoopConfig(projectDir);
+    if (isResult(cfg))
+        return cfg;
+    const p = loopPaths(projectDir);
+    try {
+        if ((await currentBranch(projectDir)) === p.branch) {
+            return fail(`the main tree is checked out on ${p.branch}; switch branches first`);
+        }
+    }
+    catch {
+        // An unborn HEAD (no commits) cannot host a worktree or be diffed.
+        return fail("the repository has no commits yet (unborn HEAD) — make an initial commit first");
+    }
+    if (!fs.existsSync(path.join(projectDir, cfg.ledger))) {
+        return fail(`ledger ${cfg.ledger} not found — write it first (see the omh-loop skill)`);
+    }
+    const ordersDir = path.join(projectDir, cfg.workOrders);
+    const orders = fs.existsSync(ordersDir) ? fs.readdirSync(ordersDir).filter((f) => f.endsWith(".md")) : [];
+    if (orders.length === 0)
+        return fail(`no work order found in ${cfg.workOrders}/ — the loop has nothing it may do`);
+    const existing = readRun(projectDir);
+    if (existing && isRunLive(existing, options)) {
+        return fail(`a loop is already running (run ${existing.runId}, pid ${existing.pid}); \`omh loop stop\` first`);
+    }
+    if (existing?.childPid !== undefined) {
+        // A SIGKILLed supervisor can leave its turn running; two loops must not
+        // share the worktree, so the orphan has to be stopped first.
+        try {
+            process.kill(-existing.childPid, 0);
+            // The group exists. A dead leader with surviving members can only be
+            // our own turn's remnants (pid reuse needs a living leader), and a
+            // living leader must actually be the runtime; only a reused pid on an
+            // unrelated group is safe to reclaim past.
+            if (isOurTurnGroup(existing.childPid, existing.runtime)) {
+                return fail(`run ${existing.runId} left an orphaned turn still running (pid ${existing.childPid}); \`omh loop stop\` first`);
+            }
+        }
+        catch {
+            // group gone — safe to reclaim
+        }
+    }
+    pruneRuns(projectDir, 5);
+    // Only start clears the flag. A stop issued between here and the
+    // supervisor acquiring the run must not be lost, so run never clears it.
+    fs.rmSync(p.stopFlag, { force: true });
+    const runId = newRunId();
+    const dir = runDir(p, runId);
+    fs.mkdirSync(dir, { recursive: true });
+    const logFd = fs.openSync(path.join(dir, "supervisor.log"), "a");
+    const spawnImpl = options.spawnImpl ?? ((cmd, args, opts) => spawn(cmd, args, opts));
+    const child = spawnImpl(process.execPath, [...process.execArgv, process.argv[1], "loop", "run", "--run-id", runId, "-d", projectDir], {
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+        env: { ...process.env, OMH_SKIP_VERSION_CHECK: "1" },
+    });
+    // Wait until the supervisor owns the run (or died trying) before letting go.
+    const acquired = await new Promise((resolve) => {
+        let done = false;
+        const settle = (v) => {
+            if (done)
+                return;
+            done = true;
+            clearInterval(poll);
+            clearTimeout(limit);
+            resolve(v);
+        };
+        child.once("exit", (code) => settle(code ?? 1));
+        const poll = setInterval(() => {
+            if (readRun(projectDir)?.runId === runId)
+                settle("acquired");
+        }, 100);
+        const limit = setTimeout(() => settle(child.exitCode ?? 1), options.acquireTimeoutMs ?? 15_000);
+    });
+    fs.closeSync(logFd);
+    // A very fast goal can run to completion — and release run.json — before
+    // our first poll ever sees the record. Exit 0 plus events for this run id
+    // is a finished loop, not a failed start.
+    if (acquired === 0 && readEvents(projectDir, runId).length > 0) {
+        const last = readEvents(projectDir, runId).at(-1);
+        console.log(chalk.green(`omh loop: started run ${runId} (pid ${child.pid ?? "?"}) — it already finished (${last?.kind ?? "done"})`));
+        console.log(`  events: ${path.join(dir, "events.jsonl")}`);
+        return { exitCode: 0 };
+    }
+    if (acquired !== "acquired") {
+        // Always let go of the handle: a still-running child would otherwise keep
+        // this CLI process alive until the whole loop finished.
+        child.unref();
+        const stillRunning = child.exitCode === null;
+        console.error(chalk.red(acquired === 3
+            ? "omh loop: another loop is already running"
+            : stillRunning
+                ? `omh loop: the supervisor did not acquire the run within the timeout — see ${path.join(dir, "supervisor.log")}`
+                : `omh loop: the supervisor exited with code ${acquired} before starting — see ${path.join(dir, "supervisor.log")}`));
+        // Exit 0 without any recorded event is not a success we can vouch for.
+        return { exitCode: acquired === 0 ? 1 : acquired };
+    }
+    child.unref();
+    console.log(chalk.green(`omh loop: started run ${runId} (pid ${child.pid ?? "?"})`));
+    console.log(`  events: ${path.join(dir, "events.jsonl")}`);
+    console.log(`  watch:  omh loop status  |  tail -f ${path.join(dir, "events.jsonl")}`);
+    console.log("  stop:   omh loop stop");
+    return { exitCode: 0 };
+}
+export async function loopRunCommand(options) {
+    const projectDir = path.resolve(options.projectDir ?? process.cwd());
+    const cfg = await loadLoopConfig(projectDir);
+    if (isResult(cfg))
+        return cfg;
+    const run = options.supervisorImpl ?? ((o) => runSupervisor(o));
+    const exit = await run({ projectDir, cfg, runId: options.runId });
+    // Whatever a turn left behind in our process group goes with us.
+    (options.sweepImpl ?? sweepOwnGroup)();
+    switch (exit) {
+        case "complete":
+        case "stopped":
+            return { exitCode: 0 };
+        case "already-running":
+            return { exitCode: 3 };
+        case "failed":
+            return { exitCode: 1 };
+    }
+}
+export async function loopStopCommand(options = {}) {
+    const projectDir = path.resolve(options.projectDir ?? process.cwd());
+    const run = readRun(projectDir);
+    // Even with no record, stopLoop lays down the stop flag so a supervisor
+    // mid-acquire still sees the request.
+    await (options.stopImpl ?? stopLoop)(projectDir, { graceMs: options.now ? 1000 : 10_000 });
+    if (!run) {
+        console.log("omh loop: no active loop (stop flag recorded)");
+        return { exitCode: 0 };
+    }
+    console.log(chalk.green(`omh loop: stopped run ${run.runId}`));
+    return { exitCode: 0 };
+}
+export async function loopStatusCommand(options = {}) {
+    const projectDir = path.resolve(options.projectDir ?? process.cwd());
+    const run = readRun(projectDir);
+    if (!run) {
+        console.log("omh loop: no active loop");
+        return { exitCode: 0 };
+    }
+    const live = isRunLive(run, options);
+    const events = readEvents(projectDir, run.runId);
+    const last = events.at(-1);
+    console.log(`run:       ${run.runId} (${live ? "running" : "not running — stale record"})`);
+    console.log(`pid:       ${run.pid}`);
+    console.log(`runtime:   ${run.runtime}`);
+    console.log(`iteration: ${run.iteration}`);
+    console.log(`cwd:       ${run.cwd}`);
+    if (last)
+        console.log(`last:      ${last.kind}${last.message ? ` — ${last.message}` : ""} (${last.ts})`);
+    console.log(`events:    ${path.join(runDir(loopPaths(projectDir), run.runId), "events.jsonl")}`);
+    return { exitCode: 0 };
+}
+export async function loopCleanCommand(options = {}) {
+    const projectDir = path.resolve(options.projectDir ?? process.cwd());
+    const p = loopPaths(projectDir);
+    await stopLoop(projectDir, { graceMs: 5000 });
+    try {
+        await removeWorktree(projectDir, { branch: options.branch });
+    }
+    catch (err) {
+        if (!(err instanceof WorktreeError))
+            throw err;
+        return fail(err.message);
+    }
+    fs.rmSync(p.stopFlag, { force: true });
+    fs.rmSync(p.runJson, { force: true });
+    console.log(chalk.green(`omh loop: cleaned worktree${options.branch ? ` and branch ${p.branch}` : ""}`));
+    return { exitCode: 0 };
+}

package/dist/cli/index.js

@@ -124,6 +124,62 @@ export function createCli() {
         const { catalogInfoCommand } = await import("./commands/catalog.js");
         await catalogInfoCommand(blockId);
     });
+    const loopCmd = program
+        .command("loop")
+        .description("Run the autonomous loop (see the omh-loop skill)");
+    loopCmd
+        .command("start")
+        .description("Start the loop supervisor in the background")
+        .option("-d, --project-dir <dir>", "Project directory")
+        .action(async (options) => {
+        const { loopStartCommand } = await import("./commands/loop.js");
+        const result = await loopStartCommand(options);
+        if (result.exitCode !== 0)
+            process.exitCode = result.exitCode;
+    });
+    loopCmd
+        .command("run")
+        .description("Run the loop supervisor in the foreground (used by start)")
+        .requiredOption("--run-id <id>", "Run identifier")
+        .option("-d, --project-dir <dir>", "Project directory")
+        .action(async (options) => {
+        const { loopRunCommand } = await import("./commands/loop.js");
+        const result = await loopRunCommand(options);
+        if (result.exitCode !== 0)
+            process.exitCode = result.exitCode;
+    });
+    loopCmd
+        .command("stop")
+        .description("Stop the running loop")
+        .option("--now", "Skip the grace period")
+        .option("-d, --project-dir <dir>", "Project directory")
+        .action(async (options) => {
+        const { loopStopCommand } = await import("./commands/loop.js");
+        const result = await loopStopCommand(options);
+        if (result.exitCode !== 0)
+            process.exitCode = result.exitCode;
+    });
+    loopCmd
+        .command("status")
+        .description("Show the current loop run")
+        .option("-d, --project-dir <dir>", "Project directory")
+        .action(async (options) => {
+        const { loopStatusCommand } = await import("./commands/loop.js");
+        const result = await loopStatusCommand(options);
+        if (result.exitCode !== 0)
+            process.exitCode = result.exitCode;
+    });
+    loopCmd
+        .command("clean")
+        .description("Remove the loop worktree and stale state")
+        .option("--branch", "Also delete the omh-loop branch")
+        .option("-d, --project-dir <dir>", "Project directory")
+        .action(async (options) => {
+        const { loopCleanCommand } = await import("./commands/loop.js");
+        const result = await loopCleanCommand(options);
+        if (result.exitCode !== 0)
+            process.exitCode = result.exitCode;
+    });
     const hookCmd = program
         .command("hook")
         .description("Manage hooks");