@graypark/loophaus 2.1.2 → 3.1.0

package/bin/loophaus.mjs

@@ -26,14 +26,24 @@ function getHost() {
 
 const host = getHost();
 
+function getFlag(flag) {
+  const idx = args.indexOf(flag);
+  if (idx !== -1 && args[idx + 1] && !args[idx + 1].startsWith("-")) return args[idx + 1];
+  return undefined;
+}
+
 if (showHelp || command === "help") {
   console.log(`loophaus — Control plane for coding agents
 
 Usage:
   npx @graypark/loophaus install [--host <name>] [--force] [--dry-run]
   npx @graypark/loophaus uninstall [--host <name>]
-  npx @graypark/loophaus status
-  npx @graypark/loophaus stats
+  npx @graypark/loophaus status [--name <loop>]
+  npx @graypark/loophaus stats [--name <loop>]
+  npx @graypark/loophaus watch
+  npx @graypark/loophaus replay <trace-file> [--speed 2]
+  npx @graypark/loophaus compare <trace1> <trace2>
+  npx @graypark/loophaus loops
   npx @graypark/loophaus --version
 
 Hosts:
@@ -47,6 +57,7 @@ Options:
   --host <name>  Target a specific host
   --claude       Shorthand for --host claude-code
   --kiro         Shorthand for --host kiro-cli
+  --name <loop>  Target a named loop (multi-loop)
   --local        Install to project-local .codex/ (Codex only)
   --force        Overwrite existing installation
   --dry-run      Preview changes without modifying files
@@ -117,10 +128,11 @@ async function runUninstall() {
 }
 
 async function runStatus() {
+  const name = getFlag("--name");
   const { read } = await import("../store/state-store.mjs");
-  const state = await read();
+  const state = await read(undefined, name);
   if (!state.active) {
-    console.log("No active loop.");
+    console.log(name ? `No active loop: ${name}` : "No active loop.");
     return;
   }
   const iterInfo = state.maxIterations > 0
@@ -128,6 +140,7 @@ async function runStatus() {
     : `${state.currentIteration}`;
   console.log(`Loop Status`);
   console.log(`\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+  if (name) console.log(`Name:       ${name}`);
   console.log(`Active:     yes`);
   console.log(`Iteration:  ${iterInfo}`);
   console.log(`Promise:    ${state.completionPromise || "(none)"}`);
@@ -150,8 +163,22 @@ async function runStatus() {
   } catch { /* no prd.json */ }
 }
 
+async function runLoops() {
+  const { listLoops } = await import("../core/loop-registry.mjs");
+  const loops = await listLoops();
+  if (loops.length === 0) { console.log("No active loops."); return; }
+  console.log("Active Loops");
+  console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  for (const l of loops) {
+    const status = l.active ? "active" : "done";
+    const iter = l.maxIterations > 0 ? `${l.currentIteration}/${l.maxIterations}` : `${l.currentIteration}`;
+    console.log(`  ${l.name}  [${status}]  iter ${iter}`);
+  }
+}
+
 async function runStats() {
   const { readTrace } = await import("../core/event-logger.mjs");
+  const { formatCost } = await import("../core/cost-tracker.mjs");
   const events = await readTrace();
   if (events.length === 0) {
     console.log("No trace data found. Run a loop first.");
@@ -168,15 +195,192 @@ async function runStats() {
     console.log(`Last stop reason: ${lastStop.reason || "unknown"}`);
     console.log(`Last stop at:     ${lastStop.ts || "unknown"}`);
   }
+
+  const costEvents = events.filter(e => e.event === "cost" || e.totalCost);
+  if (costEvents.length > 0) {
+    const totalCost = costEvents.reduce((s, e) => s + (e.totalCost || 0), 0);
+    console.log(`Estimated cost:   ${formatCost(totalCost)}`);
+  }
+
   console.log(`Trace file:       .loophaus/trace.jsonl (${events.length} events)`);
 }
 
+async function runWatch() {
+  const { getTracePath } = await import("../core/event-logger.mjs");
+  const { watch: fsWatch } = await import("node:fs");
+  const { readFile, stat } = await import("node:fs/promises");
+  const tracePath = getTracePath();
+
+  console.log(`Watching ${tracePath}...`);
+  console.log("(Ctrl+C to stop)\n");
+
+  let lastSize = 0;
+  try {
+    const s = await stat(tracePath);
+    lastSize = s.size;
+  } catch { /* file doesn't exist yet */ }
+
+  const COLORS = {
+    iteration: "\x1b[36m",
+    stop: "\x1b[31m",
+    continue: "\x1b[32m",
+    error: "\x1b[31m",
+    cost: "\x1b[33m",
+    state_change: "\x1b[35m",
+    verify_script: "\x1b[32m",
+    verify_failed: "\x1b[31m",
+    story_complete: "\x1b[32m",
+    loop_start: "\x1b[36m",
+    loop_end: "\x1b[36m",
+  };
+  const RESET = "\x1b[0m";
+
+  function printEvent(line) {
+    try {
+      const e = JSON.parse(line);
+      const color = COLORS[e.event] || "";
+      const time = e.ts ? new Date(e.ts).toLocaleTimeString() : "";
+      const detail = e.iteration ? ` iter=${e.iteration}` : e.reason ? ` reason=${e.reason}` : "";
+      console.log(`${color}[${time}] ${e.event}${detail}${RESET}`);
+    } catch { /* skip malformed */ }
+  }
+
+  try {
+    const raw = await readFile(tracePath, "utf-8");
+    const lines = raw.trim().split("\n").slice(-20);
+    for (const line of lines) printEvent(line);
+    if (lines.length > 0) console.log("--- live ---\n");
+  } catch { /* no file yet */ }
+
+  const { dirname: pathDirname } = await import("node:path");
+  const dir = pathDirname(tracePath);
+  try {
+    fsWatch(dir, { recursive: false }, async () => {
+      try {
+        const s = await stat(tracePath);
+        if (s.size > lastSize) {
+          const raw = await readFile(tracePath, "utf-8");
+          const lines = raw.trim().split("\n");
+          const newLines = [];
+          let pos = 0;
+          for (const line of lines) {
+            pos += Buffer.byteLength(line + "\n");
+            if (pos > lastSize) newLines.push(line);
+          }
+          for (const line of newLines) printEvent(line);
+          lastSize = s.size;
+        }
+      } catch { /* read error */ }
+    });
+  } catch {
+    console.log("Cannot watch file. Make sure .loophaus/ directory exists.");
+    process.exit(1);
+  }
+
+  process.stdin.resume();
+}
+
+async function runReplay() {
+  const file = args[1];
+  if (!file) {
+    console.log("Usage: loophaus replay <trace-file> [--speed 2]");
+    process.exit(1);
+  }
+  const speedRaw = getFlag("--speed") || "1";
+  const speed = speedRaw === "instant" ? 999999 : (parseFloat(speedRaw) || 1);
+  const speedLabel = speed >= 999999 ? "instant" : `${speed}x`;
+
+  const { readTrace } = await import("../core/event-logger.mjs");
+  const { replayTrace, analyzeTrace } = await import("../core/trace-analyzer.mjs");
+
+  let events;
+  if (file === ".loophaus/trace.jsonl" || file === "trace.jsonl") {
+    events = await readTrace();
+  } else {
+    const { readFile } = await import("node:fs/promises");
+    const raw = await readFile(file, "utf-8");
+    events = raw.trim().split("\n").map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  }
+
+  if (events.length === 0) { console.log("No events found."); return; }
+
+  const replayed = replayTrace(events, speed);
+  const analysis = analyzeTrace(events);
+
+  console.log(`Replaying ${events.length} events (${speedLabel})\n`);
+
+  const COLORS = { iteration: "\x1b[36m", stop: "\x1b[31m", continue: "\x1b[32m", error: "\x1b[31m", cost: "\x1b[33m", state_change: "\x1b[35m", verify_script: "\x1b[32m", verify_failed: "\x1b[31m", story_complete: "\x1b[32m", loop_start: "\x1b[36m", loop_end: "\x1b[36m" };
+  const RESET = "\x1b[0m";
+
+  let prevMs = 0;
+  for (const e of replayed) {
+    const delay = speed >= 999999 ? 0 : e.relativeMs - prevMs;
+    if (delay > 0) await new Promise(r => setTimeout(r, delay));
+    prevMs = e.relativeMs;
+
+    const color = COLORS[e.event] || "";
+    const time = e.ts ? new Date(e.ts).toLocaleTimeString() : "";
+    const detail = e.iteration ? ` iter=${e.iteration}` : e.reason ? ` reason=${e.reason}` : "";
+    console.log(`${color}[${time}] ${e.event}${detail}${RESET}`);
+  }
+
+  console.log(`\n--- Summary ---`);
+  console.log(`Iterations: ${analysis.iterations}`);
+  console.log(`Duration: ${Math.round(analysis.durationMs / 1000)}s`);
+  if (analysis.totalCost > 0) console.log(`Cost: $${analysis.totalCost.toFixed(4)}`);
+  if (analysis.lastStopReason) console.log(`Stop reason: ${analysis.lastStopReason}`);
+}
+
+async function runCompare() {
+  const file1 = args[1];
+  const file2 = args[2];
+  if (!file1 || !file2) {
+    console.log("Usage: loophaus compare <trace1> <trace2>");
+    process.exit(1);
+  }
+
+  const { readFile } = await import("node:fs/promises");
+  const { compareTraces } = await import("../core/trace-analyzer.mjs");
+
+  function loadTrace(file) {
+    return readFile(file, "utf-8").then(raw =>
+      raw.trim().split("\n").map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean)
+    );
+  }
+
+  const [t1, t2] = await Promise.all([loadTrace(file1), loadTrace(file2)]);
+  const result = compareTraces(t1, t2);
+
+  console.log("Loop Comparison");
+  console.log("═══════════════\n");
+
+  const fmt = (label, v1, v2, diff, unit = "") => {
+    const arrow = diff > 0 ? `+${diff}` : `${diff}`;
+    const color = diff > 0 ? "\x1b[31m" : diff < 0 ? "\x1b[32m" : "";
+    const reset = "\x1b[0m";
+    console.log(`  ${label.padEnd(20)} ${String(v1).padStart(8)}${unit}  vs  ${String(v2).padStart(8)}${unit}  ${color}(${arrow}${unit})${reset}`);
+  };
+
+  fmt("Iterations", result.trace1.iterations, result.trace2.iterations, result.diff.iterations);
+  fmt("Duration", Math.round(result.trace1.durationMs / 1000), Math.round(result.trace2.durationMs / 1000), Math.round(result.diff.durationMs / 1000), "s");
+  fmt("Stories done", result.trace1.storiesCompleted, result.trace2.storiesCompleted, result.diff.storiesCompleted);
+  if (result.trace1.totalCost || result.trace2.totalCost) {
+    fmt("Cost", result.trace1.totalCost.toFixed(4), result.trace2.totalCost.toFixed(4), result.diff.totalCost.toFixed(4), "$");
+  }
+  fmt("Errors", result.trace1.errors, result.trace2.errors, result.diff.errors);
+  console.log("");
+}
+
 try {
   switch (command) {
     case "install": await runInstall(); break;
     case "uninstall": await runUninstall(); break;
     case "status": await runStatus(); break;
     case "stats": await runStats(); break;
+    case "loops": await runLoops(); break;
+    case "watch": await runWatch(); break;
+    case "replay": await runReplay(); break;
+    case "compare": await runCompare(); break;
     default:
       if (command.startsWith("-")) {
         await runInstall();

package/bin/uninstall.mjs

@@ -14,7 +14,7 @@ import {
   getClaudeInstalledPluginsPath,
   getAgentsSkillsDir,
 } from "../lib/paths.mjs";
-import { getStatePath } from "../lib/state.mjs";
+import { getStatePath } from "../store/state-store.mjs";
 
 const RALPH_HOOK_MARKER = "loophaus";
 

package/codex/commands/cancel-ralph.md

@@ -17,7 +17,7 @@ To cancel the Ralph loop:
 
    ```bash
    node -e "
-   import { readState, writeState } from '${RALPH_CODEX_ROOT}/lib/state.mjs';
+   import { readState, writeState } from '${RALPH_CODEX_ROOT}/store/state-store.mjs';
    const state = await readState();
    const iter = state.currentIteration;
    state.active = false;

package/codex/commands/ralph-loop.md

@@ -20,7 +20,7 @@ Run this command to initialize the Ralph loop state file:
 
 ```bash
 node -e "
-import { writeState } from '${RALPH_CODEX_ROOT}/lib/state.mjs';
+import { writeState } from '${RALPH_CODEX_ROOT}/store/state-store.mjs';
 await writeState({
   active: true,
   prompt: PROMPT_HERE,

package/core/cost-tracker.mjs

@@ -0,0 +1,44 @@
+// core/cost-tracker.mjs — Token cost estimation. Prices in USD per 1M tokens.
+
+const MODEL_PRICES = {
+  "claude-opus-4": { input: 15, output: 75 },
+  "claude-sonnet-4": { input: 3, output: 15 },
+  "claude-haiku-4": { input: 0.8, output: 4 },
+  "gpt-4.1": { input: 2, output: 8 },
+  "gpt-4.1-mini": { input: 0.4, output: 1.6 },
+  "gpt-4o": { input: 2.5, output: 10 },
+  "o4-mini": { input: 1.1, output: 4.4 },
+  "default": { input: 3, output: 15 },
+};
+
+export function estimateCost(model, inputTokens, outputTokens) {
+  const prices = MODEL_PRICES[model] || MODEL_PRICES["default"];
+  const inputCost = (inputTokens / 1_000_000) * prices.input;
+  const outputCost = (outputTokens / 1_000_000) * prices.output;
+  return { inputCost, outputCost, totalCost: inputCost + outputCost };
+}
+
+export function formatCost(cost) {
+  if (cost < 0.01) return `$${(cost * 100).toFixed(2)}¢`;
+  return `$${cost.toFixed(4)}`;
+}
+
+export function createTracker() {
+  const records = [];
+  return {
+    record(label, model, inputTokens, outputTokens) {
+      const cost = estimateCost(model, inputTokens, outputTokens);
+      records.push({ label, model, inputTokens, outputTokens, ...cost, ts: new Date().toISOString() });
+      return cost;
+    },
+    summary() {
+      const totalInput = records.reduce((s, r) => s + r.inputTokens, 0);
+      const totalOutput = records.reduce((s, r) => s + r.outputTokens, 0);
+      const totalCost = records.reduce((s, r) => s + r.totalCost, 0);
+      return { totalInput, totalOutput, totalCost, records: records.length };
+    },
+    getRecords() { return [...records]; },
+  };
+}
+
+export { MODEL_PRICES };

package/core/engine.mjs

@@ -41,6 +41,22 @@ export function evaluateStopHook(input, state) {
     }
   }
 
+  // Check verify script result (pre-computed by caller)
+  if (nextState.verifyScript && input.verify_result) {
+    if (input.verify_result.passed) {
+      nextState.active = false;
+      events.push({ event: "stop", reason: "verify_script", script: nextState.verifyScript });
+      return {
+        decision: "allow",
+        nextState,
+        events,
+        output: null,
+        message: `Loop: verify script passed.`,
+      };
+    }
+    events.push({ event: "verify_failed", script: nextState.verifyScript, output: input.verify_result.output || "" });
+  }
+
   if (input.stop_hook_active === true) {
     if (!input.has_pending_stories) {
       nextState.active = false;

package/core/events.mjs

@@ -0,0 +1,44 @@
+// Event type constants and filter utilities
+
+export const EventType = {
+  ITERATION: "iteration",
+  STOP: "stop",
+  CONTINUE: "continue",
+  DECISION: "decision",
+  STORY_COMPLETE: "story_complete",
+  TEST_RESULT: "test_result",
+  COST: "cost",
+  VERIFY_SCRIPT: "verify_script",
+  VERIFY_FAILED: "verify_failed",
+  LOOP_START: "loop_start",
+  LOOP_END: "loop_end",
+  CHECKPOINT: "checkpoint",
+  ERROR: "error",
+  STATE_CHANGE: "state_change",
+};
+
+export function filterByType(events, type) {
+  return events.filter(e => e.event === type);
+}
+
+export function filterByTimeRange(events, start, end) {
+  return events.filter(e => {
+    const ts = new Date(e.ts).getTime();
+    return ts >= start.getTime() && ts <= end.getTime();
+  });
+}
+
+export function filterByLoopId(events, loopId) {
+  return events.filter(e => e.loop_id === loopId);
+}
+
+export function summarizeEvents(events) {
+  const counts = {};
+  for (const e of events) {
+    counts[e.event] = (counts[e.event] || 0) + 1;
+  }
+  const first = events[0];
+  const last = events[events.length - 1];
+  const durationMs = first && last ? new Date(last.ts).getTime() - new Date(first.ts).getTime() : 0;
+  return { counts, total: events.length, durationMs, firstTs: first?.ts, lastTs: last?.ts };
+}

package/core/io-helpers.mjs

@@ -0,0 +1,33 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function getLastAssistantText(transcriptPath) {
+  if (!transcriptPath) return "";
+  try {
+    const raw = await readFile(transcriptPath, "utf-8");
+    const lines = raw.trim().split("\n");
+    const recent = lines.filter((line) => {
+      try { return JSON.parse(line).role === "assistant"; } catch { return false; }
+    }).slice(-100);
+    for (let i = recent.length - 1; i >= 0; i--) {
+      try {
+        const obj = JSON.parse(recent[i]);
+        const contents = obj.message?.content || obj.content;
+        if (Array.isArray(contents)) {
+          for (let j = contents.length - 1; j >= 0; j--) {
+            if (contents[j].type === "text" && contents[j].text) return contents[j].text;
+          }
+        } else if (typeof contents === "string") return contents;
+      } catch { /* skip */ }
+    }
+  } catch { /* not found */ }
+  return "";
+}
+
+export async function hasPendingStories(cwd) {
+  try {
+    const raw = await readFile(join(cwd || process.cwd(), "prd.json"), "utf-8");
+    const prd = JSON.parse(raw);
+    return Array.isArray(prd.userStories) && prd.userStories.some((s) => s.passes === false);
+  } catch { return false; }
+}

package/core/loop-registry.mjs

@@ -0,0 +1,37 @@
+// core/loop-registry.mjs — Multi-loop registry for named loop instances
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function listLoops(cwd) {
+  const loopsDir = join(cwd || process.cwd(), ".loophaus", "loops");
+  const loops = [];
+  try {
+    const entries = await readdir(loopsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const statePath = join(loopsDir, entry.name, "state.json");
+      try {
+        const raw = await readFile(statePath, "utf-8");
+        const state = JSON.parse(raw);
+        loops.push({ name: entry.name, ...state });
+      } catch {
+        loops.push({ name: entry.name, active: false, error: "unreadable" });
+      }
+    }
+  } catch { /* no loops dir */ }
+
+  const defaultPath = join(cwd || process.cwd(), ".loophaus", "state.json");
+  try {
+    const raw = await readFile(defaultPath, "utf-8");
+    const state = JSON.parse(raw);
+    loops.unshift({ name: "(default)", ...state });
+  } catch { /* no default */ }
+
+  return loops;
+}
+
+export async function getLoop(name, cwd) {
+  const loops = await listLoops(cwd);
+  return loops.find(l => l.name === name) || null;
+}

package/core/state.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Loophaus State",
+  "type": "object",
+  "required": ["active", "prompt", "maxIterations", "currentIteration"],
+  "properties": {
+    "active": { "type": "boolean" },
+    "prompt": { "type": "string" },
+    "completionPromise": { "type": "string" },
+    "maxIterations": { "type": "integer", "minimum": 0 },
+    "currentIteration": { "type": "integer", "minimum": 0 },
+    "sessionId": { "type": "string" },
+    "name": { "type": "string", "description": "Loop name for multi-loop support" },
+    "verifyScript": { "type": "string", "description": "Path to verification script" },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "cost": {
+      "type": "object",
+      "properties": {
+        "totalTokens": { "type": "integer" },
+        "estimatedCost": { "type": "number" }
+      }
+    }
+  }
+}

package/core/trace-analyzer.mjs

@@ -0,0 +1,51 @@
+// Pure functions for trace analysis
+
+import { EventType, filterByType, summarizeEvents } from "./events.mjs";
+
+export function analyzeTrace(events) {
+  const summary = summarizeEvents(events);
+  const iterations = filterByType(events, EventType.ITERATION);
+  const stops = filterByType(events, EventType.STOP);
+  const errors = filterByType(events, EventType.ERROR);
+  const stories = filterByType(events, EventType.STORY_COMPLETE);
+  const costs = filterByType(events, EventType.COST);
+
+  const totalCost = costs.reduce((s, e) => s + (e.totalCost || 0), 0);
+  const lastStop = stops[stops.length - 1];
+
+  return {
+    ...summary,
+    iterations: iterations.length,
+    stops: stops.length,
+    errors: errors.length,
+    storiesCompleted: stories.length,
+    totalCost,
+    lastStopReason: lastStop?.reason || null,
+    avgIterationMs: iterations.length > 1 ? summary.durationMs / iterations.length : 0,
+  };
+}
+
+export function compareTraces(trace1, trace2) {
+  const a1 = analyzeTrace(trace1);
+  const a2 = analyzeTrace(trace2);
+
+  return {
+    trace1: a1,
+    trace2: a2,
+    diff: {
+      iterations: a2.iterations - a1.iterations,
+      totalCost: a2.totalCost - a1.totalCost,
+      durationMs: a2.durationMs - a1.durationMs,
+      storiesCompleted: a2.storiesCompleted - a1.storiesCompleted,
+    },
+  };
+}
+
+export function replayTrace(events, speed = 1) {
+  if (events.length === 0) return [];
+  const firstTs = new Date(events[0].ts).getTime();
+  return events.map(e => ({
+    ...e,
+    relativeMs: Math.round((new Date(e.ts).getTime() - firstTs) / speed),
+  }));
+}

package/core/validate.mjs

@@ -0,0 +1,51 @@
+// core/validate.mjs — Zero-dep runtime schema validation
+
+const STATE_REQUIRED = {
+  active: "boolean",
+  prompt: "string",
+  maxIterations: "number",
+  currentIteration: "number",
+};
+
+const STATE_OPTIONAL = {
+  completionPromise: "string",
+  sessionId: "string",
+  name: "string",
+  verifyScript: "string",
+  startedAt: "string",
+  cost: "object",
+};
+
+export function validateState(obj) {
+  const errors = [];
+  if (typeof obj !== "object" || obj === null) {
+    return { valid: false, errors: ["State must be an object"] };
+  }
+  for (const [key, type] of Object.entries(STATE_REQUIRED)) {
+    if (!(key in obj)) errors.push(`Missing required field: ${key}`);
+    else if (typeof obj[key] !== type) errors.push(`${key} must be ${type}, got ${typeof obj[key]}`);
+  }
+  for (const [key, type] of Object.entries(STATE_OPTIONAL)) {
+    if (key in obj && obj[key] !== undefined && obj[key] !== null && typeof obj[key] !== type) {
+      errors.push(`${key} must be ${type}, got ${typeof obj[key]}`);
+    }
+  }
+  if (typeof obj.maxIterations === "number" && obj.maxIterations < 0) {
+    errors.push("maxIterations must be >= 0");
+  }
+  if (typeof obj.currentIteration === "number" && obj.currentIteration < 0) {
+    errors.push("currentIteration must be >= 0");
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+export function validateLoopConfig(obj) {
+  const errors = [];
+  if (typeof obj !== "object" || obj === null) {
+    return { valid: false, errors: ["Config must be an object"] };
+  }
+  if (obj.protocol_version && obj.protocol_version !== "1.0") {
+    errors.push(`Unsupported protocol version: ${obj.protocol_version}`);
+  }
+  return { valid: errors.length === 0, errors };
+}

package/hooks/stop-hook.mjs

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { evaluateStopHook } from "../core/engine.mjs";
+import { getLastAssistantText, hasPendingStories } from "../core/io-helpers.mjs";
 import { read as readState, write as writeState } from "../store/state-store.mjs";
 import { logEvents } from "../core/event-logger.mjs";
 
@@ -12,37 +11,6 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf-8");
 }
 
-async function getLastAssistantText(transcriptPath) {
-  if (!transcriptPath) return "";
-  try {
-    const raw = await readFile(transcriptPath, "utf-8");
-    const lines = raw.trim().split("\n");
-    const recent = lines.filter((line) => {
-      try { return JSON.parse(line).role === "assistant"; } catch { return false; }
-    }).slice(-100);
-    for (let i = recent.length - 1; i >= 0; i--) {
-      try {
-        const obj = JSON.parse(recent[i]);
-        const contents = obj.message?.content || obj.content;
-        if (Array.isArray(contents)) {
-          for (let j = contents.length - 1; j >= 0; j--) {
-            if (contents[j].type === "text" && contents[j].text) return contents[j].text;
-          }
-        } else if (typeof contents === "string") return contents;
-      } catch { /* skip */ }
-    }
-  } catch { /* not found */ }
-  return "";
-}
-
-async function hasPendingStories(cwd) {
-  try {
-    const raw = await readFile(join(cwd || process.cwd(), "prd.json"), "utf-8");
-    const prd = JSON.parse(raw);
-    return Array.isArray(prd.userStories) && prd.userStories.some((s) => s.passes === false);
-  } catch { return false; }
-}
-
 async function main() {
   let hookInput = {};
   try {
@@ -57,10 +25,25 @@ async function main() {
     await getLastAssistantText(hookInput.transcript_path || null);
   const pending = await hasPendingStories(cwd);
 
+  // Run verify script if configured
+  let verifyResult = null;
+  if (state.verifyScript) {
+    try {
+      const { execFile } = await import("node:child_process");
+      const { promisify } = await import("node:util");
+      const execFileAsync = promisify(execFile);
+      const { stdout: vOut } = await execFileAsync(state.verifyScript, [], { cwd, timeout: 30_000 });
+      verifyResult = { passed: true, output: vOut.trim() };
+    } catch (err) {
+      verifyResult = { passed: false, output: err.stderr || err.message };
+    }
+  }
+
   const input = {
     ...hookInput,
     last_assistant_text: lastText,
     has_pending_stories: pending,
+    verify_result: verifyResult,
   };
 
   const result = evaluateStopHook(input, state);

package/lib/stop-hook-core.mjs

@@ -1,162 +1,42 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { evaluateStopHook, extractPromise } from "../core/engine.mjs";
+import { getLastAssistantText, hasPendingStories } from "../core/io-helpers.mjs";
 
-export function extractPromise(text, promisePhrase) {
-  const regex = new RegExp(
-    `<promise>\\s*${escapeRegex(promisePhrase)}\\s*</promise>`,
-    "s",
-  );
-  return regex.test(text);
-}
-
-export function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-export async function getLastAssistantText(transcriptPath) {
-  if (!transcriptPath) return "";
-  try {
-    const raw = await readFile(transcriptPath, "utf-8");
-    const lines = raw.trim().split("\n");
-    const assistantLines = lines.filter((line) => {
-      try {
-        const obj = JSON.parse(line);
-        return obj.role === "assistant";
-      } catch {
-        return false;
-      }
-    });
-    const recent = assistantLines.slice(-100);
-    for (let i = recent.length - 1; i >= 0; i--) {
-      try {
-        const obj = JSON.parse(recent[i]);
-        const contents = obj.message?.content || obj.content;
-        if (Array.isArray(contents)) {
-          for (let j = contents.length - 1; j >= 0; j--) {
-            if (contents[j].type === "text" && contents[j].text) {
-              return contents[j].text;
-            }
-          }
-        } else if (typeof contents === "string") {
-          return contents;
-        }
-      } catch {
-        // skip malformed lines
-      }
-    }
-  } catch {
-    // transcript not found or unreadable
-  }
-  return "";
-}
-
-export async function hasPendingStories(cwd) {
-  const prdPath = join(cwd || process.cwd(), "prd.json");
-  try {
-    const raw = await readFile(prdPath, "utf-8");
-    const prd = JSON.parse(raw);
-    if (!Array.isArray(prd.userStories)) return false;
-    return prd.userStories.some((s) => s.passes === false);
-  } catch {
-    return false;
-  }
-}
+export { extractPromise, getLastAssistantText, hasPendingStories };
 
 export async function processStopHook(hookInput, readStateFn, writeStateFn) {
-  const stderr = [];
   const state = await readStateFn();
 
-  // Not active — allow exit
   if (!state.active) {
     return { exitCode: 0, stdout: "", stderr: "" };
   }
 
-  // Session isolation
-  if (
-    state.sessionId &&
-    hookInput.session_id &&
-    state.sessionId !== hookInput.session_id
-  ) {
+  if (state.sessionId && hookInput.session_id && state.sessionId !== hookInput.session_id) {
     return { exitCode: 0, stdout: "", stderr: "" };
   }
 
-  // Increment iteration
-  state.currentIteration += 1;
-
-  // Check max iterations
-  if (state.maxIterations > 0 && state.currentIteration > state.maxIterations) {
-    stderr.push(
-      `Loop: max iterations (${state.maxIterations}) reached.\n`,
-    );
-    state.active = false;
-    await writeStateFn(state);
-    return { exitCode: 0, stdout: "", stderr: stderr.join("") };
-  }
+  const lastText = hookInput.last_assistant_message ||
+    await getLastAssistantText(hookInput.transcript_path || null);
+  const pending = await hasPendingStories(hookInput.cwd || process.cwd());
 
-  // Check completion promise
-  if (state.completionPromise) {
-    const lastText =
-      hookInput.last_assistant_message ||
-      (await getLastAssistantText(hookInput.transcript_path || null));
+  const input = {
+    ...hookInput,
+    last_assistant_text: lastText,
+    has_pending_stories: pending,
+  };
 
-    if (lastText && extractPromise(lastText, state.completionPromise)) {
-      stderr.push(
-        `Loop: completion promise "${state.completionPromise}" detected.\n`,
-      );
-      state.active = false;
-      await writeStateFn(state);
-      return { exitCode: 0, stdout: "", stderr: stderr.join("") };
-    }
-  }
+  const result = evaluateStopHook(input, state);
 
-  // Hybrid stop_hook_active handling:
-  // When true, the agent already continued from a previous block.
-  // Check prd.json for pending stories — only block if work remains.
-  if (hookInput.stop_hook_active === true) {
-    const cwd = hookInput.cwd || process.cwd();
-    const pending = await hasPendingStories(cwd);
+  await writeStateFn(result.nextState);
 
-    if (!pending) {
-      stderr.push(
-        "Loop: stop_hook_active=true, no pending stories. Allowing exit.\n",
-      );
-      state.active = false;
-      await writeStateFn(state);
-      return { exitCode: 0, stdout: "", stderr: stderr.join("") };
+  const stderrParts = [];
+  if (result.message) stderrParts.push(result.message);
+  for (const ev of result.events || []) {
+    if (ev.event === "continue" && ev.reason === "pending_stories") {
+      stderrParts.push("Loop: stop_hook_active=true, pending stories found. Continuing.");
     }
-
-    stderr.push(
-      "Loop: stop_hook_active=true, pending stories found. Continuing.\n",
-    );
   }
+  const stderr = stderrParts.length ? stderrParts.join("\n") + "\n" : "";
+  const stdout = result.output ? JSON.stringify(result.output) : "";
 
-  // Save updated iteration
-  await writeStateFn(state);
-
-  // Build continuation prompt
-  const iterInfo =
-    state.maxIterations > 0
-      ? `${state.currentIteration}/${state.maxIterations}`
-      : `${state.currentIteration}`;
-
-  const reason = [
-    state.prompt,
-    "",
-    "---",
-    `Loop iteration ${iterInfo}. Continue working on the task above.`,
-  ].join("\n");
-
-  const output = { decision: "block", reason };
-
-  if (state.completionPromise) {
-    output.systemMessage = `Loop iteration ${iterInfo} | To stop: output <promise>${state.completionPromise}</promise> (ONLY when TRUE)`;
-  } else {
-    output.systemMessage = `Loop iteration ${iterInfo} | No completion promise — loop runs until max iterations`;
-  }
-
-  return {
-    exitCode: 0,
-    stdout: JSON.stringify(output),
-    stderr: stderr.join(""),
-  };
+  return { exitCode: 0, stdout, stderr };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graypark/loophaus",
-  "version": "2.1.2",
+  "version": "3.1.0",
   "type": "module",
   "description": "loophaus — Control plane for coding agents. Iterative dev loops with multi-agent orchestration.",
   "license": "MIT",

package/store/state-store.mjs

@@ -1,5 +1,6 @@
 import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
 import { join, dirname } from "node:path";
+import { validateState } from "../core/validate.mjs";
 
 const DEFAULT_STATE = {
   active: false,
@@ -10,10 +11,12 @@ const DEFAULT_STATE = {
   sessionId: "",
 };
 
-export function getStatePath(cwd) {
+export function getStatePath(cwd, name) {
   if (process.env.LOOPHAUS_STATE_FILE) return process.env.LOOPHAUS_STATE_FILE;
   if (process.env.RALPH_STATE_FILE) return process.env.RALPH_STATE_FILE;
-  return join(cwd || process.cwd(), ".loophaus", "state.json");
+  const base = cwd || process.cwd();
+  if (name) return join(base, ".loophaus", "loops", name, "state.json");
+  return join(base, ".loophaus", "state.json");
 }
 
 const LEGACY_PATHS = [
@@ -21,12 +24,17 @@ const LEGACY_PATHS = [
   (cwd) => join(cwd, ".claude", "ralph-loop.local.md"),
 ];
 
-export async function read(cwd) {
-  const primary = getStatePath(cwd);
+export async function read(cwd, name) {
+  const primary = getStatePath(cwd, name);
 
   try {
     const raw = await readFile(primary, "utf-8");
-    return { ...DEFAULT_STATE, ...JSON.parse(raw) };
+    const state = { ...DEFAULT_STATE, ...JSON.parse(raw) };
+    const result = validateState(state);
+    if (!result.valid) {
+      process.stderr.write(`loophaus: state validation warning: ${result.errors.join(", ")}\n`);
+    }
+    return state;
   } catch {
     // Primary not found, try legacy paths
   }
@@ -48,8 +56,12 @@ export async function read(cwd) {
   return { ...DEFAULT_STATE };
 }
 
-export async function write(state, cwd) {
-  const statePath = getStatePath(cwd);
+export async function write(state, cwd, name) {
+  const result = validateState(state);
+  if (!result.valid) {
+    process.stderr.write(`loophaus: writing invalid state: ${result.errors.join(", ")}\n`);
+  }
+  const statePath = getStatePath(cwd, name);
   await mkdir(dirname(statePath), { recursive: true });
   const tmp = statePath + ".tmp";
   await writeFile(tmp, JSON.stringify(state, null, 2), "utf-8");
@@ -77,4 +89,15 @@ function migrateMdFormat(raw) {
   return state;
 }
 
+// Backward-compatible exports (matching lib/state.mjs interface)
+export async function readState(cwd) { return read(cwd); }
+export async function writeState(state, cwd) { return write(state, cwd); }
+export async function resetState(cwd) { return reset(cwd); }
+export async function incrementIteration(cwd) {
+  const state = await read(cwd);
+  state.currentIteration += 1;
+  await write(state, cwd);
+  return state;
+}
+
 export { DEFAULT_STATE };

package/lib/state.mjs

@@ -1,46 +0,0 @@
-import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { join, dirname } from "node:path";
-
-const DEFAULT_STATE = {
-  active: false,
-  prompt: "",
-  completionPromise: "TADA",
-  maxIterations: 20,
-  currentIteration: 0,
-  sessionId: "",
-};
-
-export function getStatePath() {
-  return (
-    process.env.LOOPHAUS_STATE_FILE ||
-    process.env.RALPH_STATE_FILE ||
-    join(process.cwd(), ".loophaus", "state.json")
-  );
-}
-
-export async function readState() {
-  const statePath = getStatePath();
-  try {
-    const raw = await readFile(statePath, "utf-8");
-    return { ...DEFAULT_STATE, ...JSON.parse(raw) };
-  } catch {
-    return { ...DEFAULT_STATE };
-  }
-}
-
-export async function writeState(state) {
-  const statePath = getStatePath();
-  await mkdir(dirname(statePath), { recursive: true });
-  await writeFile(statePath, JSON.stringify(state, null, 2), "utf-8");
-}
-
-export async function resetState() {
-  await writeState({ ...DEFAULT_STATE });
-}
-
-export async function incrementIteration() {
-  const state = await readState();
-  state.currentIteration += 1;
-  await writeState(state);
-  return state;
-}