@graypark/loophaus 3.7.0 → 3.8.0

package/README.ko.md

@@ -153,11 +153,13 @@ loophaus는 세 개의 주요 코딩 에이전트 플랫폼을 지원합니다:
 | 기능 | Claude Code | Codex CLI | Kiro CLI |
 | --- | --- | --- | --- |
 | 자동 감지 설치 | `~/.claude/` | `~/.codex/` | `~/.kiro/` |
-| Stop hook | bash 기반 | Node.js 기반 | bash 기반 |
+| Stop hook | Node.js 기반 | Node.js 기반 | Node.js 기반 |
 | 루프 실행 | Skill tool | 네이티브 커맨드 | 네이티브 커맨드 |
 | 멀티 에이전트 | Agent tool | 서브에이전트 | 서브에이전트 |
 | 상태 파일 | `.loophaus/state.json` | `.loophaus/state.json` | `.loophaus/state.json` |
 
+Windows에서도 PowerShell/CMD 기준으로 `install`, `upgrade`, `/loop` 초기화가 동작합니다. Git Bash나 WSL은 선택사항입니다.
+
 ## 설치
 
 ### 글로벌 설치 (권장)
@@ -167,6 +169,8 @@ npm install -g @graypark/loophaus
 loophaus install
 ```
 
+Windows에서는 전역 npm 실행 파일 경로(보통 `%AppData%\npm`)가 `PATH`에 포함되어 있어야 합니다.
+
 ### npx로 설치
 
 ```bash
@@ -366,6 +370,12 @@ Phase 2 — 순차 수정 (루프):
 
 ## 업데이트
 
+```bash
+loophaus upgrade
+```
+
+수동 업데이트가 필요하면:
+
 ```bash
 npm install -g @graypark/loophaus@latest
 loophaus install --force
@@ -381,7 +391,7 @@ npm uninstall -g @graypark/loophaus
 ## 개발
 
 ```bash
-npm install && npm test    # 296개 테스트
+npm install && npm test
 npm run typecheck          # TypeScript strict 모드
 npm run build              # dist/로 컴파일
 npx vitest                # watch 모드

package/README.md

@@ -119,6 +119,8 @@ That's it. The interview generates a PRD, activates the loop, and starts impleme
 
 All three platforms share the same core engine (`core/engine.ts`) and state store (`store/state-store.ts`). Platform-specific adapters handle the differences.
 
+Native Windows is supported for install, upgrade, and `/loop` initialization via PowerShell or CMD. Git Bash and WSL are optional, not required.
+
 ## Installation
 
 ### Global install (recommended)
@@ -128,6 +130,8 @@ npm install -g @graypark/loophaus
 loophaus install
 ```
 
+On Windows, ensure your global npm bin directory (typically `%AppData%\npm`) is on `PATH`.
+
 ### Via npx
 
 ```bash
@@ -283,6 +287,12 @@ Each story is sized to complete in one iteration (one context window). Dependenc
 
 ## Update
 
+```bash
+loophaus upgrade
+```
+
+Manual upgrade also works:
+
 ```bash
 npm install -g @graypark/loophaus@latest
 loophaus install --force
@@ -301,7 +311,7 @@ npm uninstall -g @graypark/loophaus
 git clone https://github.com/vcz-Gray/loophaus.git
 cd loophaus
 npm install
-npm test          # 296 test cases
+npm test
 npm run typecheck  # TypeScript strict mode
 npm run build      # Compile to dist/
 npx vitest        # watch mode

package/commands/cancel-ralph.md

@@ -1,11 +1,6 @@
 ---
 description: "Cancel active Ralph Loop"
-allowed-tools:
-  [
-    "Bash(test -f .claude/ralph-loop.local.md:*)",
-    "Bash(rm .claude/ralph-loop.local.md)",
-    "Read(.claude/ralph-loop.local.md)",
-  ]
+allowed-tools: ["Bash", "Read"]
 hide-from-slash-command-tool: "true"
 ---
 
@@ -13,11 +8,11 @@ hide-from-slash-command-tool: "true"
 
 To cancel the Ralph loop:
 
-1. Check if `.claude/ralph-loop.local.md` exists using Bash: `test -f .claude/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"`
+1. Check if `.claude/ralph-loop.local.md` exists using a cross-platform Node command.
 
 2. **If NOT_FOUND**: Say "No active Ralph loop found."
 
 3. **If EXISTS**:
    - Read `.claude/ralph-loop.local.md` to get the current iteration number from the `iteration:` field
-   - Remove the file using Bash: `rm .claude/ralph-loop.local.md`
+   - Remove the file using a cross-platform Node file command
    - Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value

package/commands/loop-plan.md

@@ -13,13 +13,9 @@ The user runs `/loop-plan` once and gets a single merged branch with all work do
 
 ## Pre-flight: Update Check
 
-Run this silently before starting:
+Run `loophaus update-check` silently before starting.
 
-```bash
-_UPDATE=$(loophaus update-check 2>/dev/null | grep "UPGRADE_AVAILABLE" || true)
-```
-
-If `_UPDATE` contains `UPGRADE_AVAILABLE`:
+If the command reports an available update:
 1. Show: `loophaus update available: v{current} → v{latest}`
 2. Ask user:
    - **A) Upgrade now** → run `loophaus upgrade`, then continue
@@ -30,7 +26,7 @@ If `_UPDATE` contains `UPGRADE_AVAILABLE`:
 If auto-upgrade is enabled (`loophaus config get autoUpgrade` returns `true`):
 - Skip prompt, run `loophaus upgrade` silently, continue.
 
-If no update or check fails: continue silently (never block the user).
+If no update is available or the check fails: continue silently and never block the user.
 
 ## Pre-flight: Skill Routing Check
 

package/commands/loop-stop.md

@@ -1,29 +1,21 @@
 ---
 description: "Stop active loop"
-allowed-tools:
-  [
-    "Bash(test -f .loophaus/state.json:*)",
-    "Bash(rm .loophaus/state.json)",
-    "Read(.loophaus/state.json)",
-    "Bash(test -f .claude/ralph-loop.local.md:*)",
-    "Bash(rm .claude/ralph-loop.local.md)",
-    "Read(.claude/ralph-loop.local.md)",
-  ]
+allowed-tools: ["Bash", "Read"]
 ---
 
 # /loop-stop — Stop Active Loop
 
-1. Check if `.loophaus/state.json` exists: `test -f .loophaus/state.json && echo "EXISTS" || echo "NOT_FOUND"`
-   - If not found, also check legacy path: `test -f .claude/ralph-loop.local.md && echo "LEGACY" || echo "NOT_FOUND"`
+1. Check if `.loophaus/state.json` exists using a cross-platform Node command.
+   - If not found, also check legacy path `.claude/ralph-loop.local.md`.
 
 2. **If NOT_FOUND** on both: Say "No active loop found."
 
 3. **If EXISTS** (.loophaus/state.json):
    - Read the file to get `currentIteration`
-   - Remove it: `rm .loophaus/state.json`
+   - Remove it with a cross-platform Node file command
    - Report: "Stopped loop at iteration N."
 
 4. **If LEGACY** (.claude/ralph-loop.local.md):
    - Read it to get the iteration field
-   - Remove it: `rm .claude/ralph-loop.local.md`
+   - Remove it with a cross-platform Node file command
    - Report: "Stopped loop at iteration N. (migrated from legacy path)"

package/commands/loop.md

@@ -1,26 +1,24 @@
 ---
 description: "Start iterative dev loop"
 argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
-allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
+allowed-tools: ["Bash"]
 ---
 
 # /loop — Start Iterative Dev Loop
 
 ## Pre-flight
 
-```bash
-_UPDATE=$(loophaus update-check 2>/dev/null | grep "UPGRADE_AVAILABLE" || true)
-```
-If update available and autoUpgrade enabled: run `loophaus upgrade` silently.
-If update available and not auto: show one-line notice `loophaus v{new} available. Run: loophaus upgrade`.
-Otherwise: continue silently.
+Run `loophaus update-check` quietly before starting.
+If it reports an available update and auto-upgrade is enabled, run `loophaus upgrade` and continue.
+If it reports an available update and auto-upgrade is disabled, show one-line notice: `loophaus update available. Run: loophaus upgrade`.
+If the check fails or no update is available, continue silently.
 
 ---
 
 Execute the setup script to initialize the loop:
 
 ```!
-"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
+node "${CLAUDE_PLUGIN_ROOT}/scripts/setup-loop.mjs" $ARGUMENTS
 ```
 
 Work on the task. When you try to exit, the stop hook feeds the SAME PROMPT back for the next iteration. Your previous work persists in files and git history.

package/commands/ralph-loop.md

@@ -1,7 +1,7 @@
 ---
 description: "Start Ralph Loop in current session"
 argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
-allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
+allowed-tools: ["Bash"]
 hide-from-slash-command-tool: "true"
 ---
 
@@ -10,7 +10,7 @@ hide-from-slash-command-tool: "true"
 Execute the setup script to initialize the Ralph loop:
 
 ```!
-"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
+node "${CLAUDE_PLUGIN_ROOT}/scripts/setup-loop.mjs" $ARGUMENTS
 ```
 
 Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.

package/dist/README.ko.md

@@ -153,11 +153,13 @@ loophaus는 세 개의 주요 코딩 에이전트 플랫폼을 지원합니다:
 | 기능 | Claude Code | Codex CLI | Kiro CLI |
 | --- | --- | --- | --- |
 | 자동 감지 설치 | `~/.claude/` | `~/.codex/` | `~/.kiro/` |
-| Stop hook | bash 기반 | Node.js 기반 | bash 기반 |
+| Stop hook | Node.js 기반 | Node.js 기반 | Node.js 기반 |
 | 루프 실행 | Skill tool | 네이티브 커맨드 | 네이티브 커맨드 |
 | 멀티 에이전트 | Agent tool | 서브에이전트 | 서브에이전트 |
 | 상태 파일 | `.loophaus/state.json` | `.loophaus/state.json` | `.loophaus/state.json` |
 
+Windows에서도 PowerShell/CMD 기준으로 `install`, `upgrade`, `/loop` 초기화가 동작합니다. Git Bash나 WSL은 선택사항입니다.
+
 ## 설치
 
 ### 글로벌 설치 (권장)
@@ -167,6 +169,8 @@ npm install -g @graypark/loophaus
 loophaus install
 ```
 
+Windows에서는 전역 npm 실행 파일 경로(보통 `%AppData%\npm`)가 `PATH`에 포함되어 있어야 합니다.
+
 ### npx로 설치
 
 ```bash
@@ -366,6 +370,12 @@ Phase 2 — 순차 수정 (루프):
 
 ## 업데이트
 
+```bash
+loophaus upgrade
+```
+
+수동 업데이트가 필요하면:
+
 ```bash
 npm install -g @graypark/loophaus@latest
 loophaus install --force
@@ -381,7 +391,7 @@ npm uninstall -g @graypark/loophaus
 ## 개발
 
 ```bash
-npm install && npm test    # 296개 테스트
+npm install && npm test
 npm run typecheck          # TypeScript strict 모드
 npm run build              # dist/로 컴파일
 npx vitest                # watch 모드

package/dist/README.md

@@ -119,6 +119,8 @@ That's it. The interview generates a PRD, activates the loop, and starts impleme
 
 All three platforms share the same core engine (`core/engine.ts`) and state store (`store/state-store.ts`). Platform-specific adapters handle the differences.
 
+Native Windows is supported for install, upgrade, and `/loop` initialization via PowerShell or CMD. Git Bash and WSL are optional, not required.
+
 ## Installation
 
 ### Global install (recommended)
@@ -128,6 +130,8 @@ npm install -g @graypark/loophaus
 loophaus install
 ```
 
+On Windows, ensure your global npm bin directory (typically `%AppData%\npm`) is on `PATH`.
+
 ### Via npx
 
 ```bash
@@ -283,6 +287,12 @@ Each story is sized to complete in one iteration (one context window). Dependenc
 
 ## Update
 
+```bash
+loophaus upgrade
+```
+
+Manual upgrade also works:
+
 ```bash
 npm install -g @graypark/loophaus@latest
 loophaus install --force
@@ -301,7 +311,7 @@ npm uninstall -g @graypark/loophaus
 git clone https://github.com/vcz-Gray/loophaus.git
 cd loophaus
 npm install
-npm test          # 296 test cases
+npm test
 npm run typecheck  # TypeScript strict mode
 npm run build      # Compile to dist/
 npx vitest        # watch mode

package/dist/bin/loophaus.js

@@ -3,6 +3,8 @@
 import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { access } from "node:fs/promises";
+import { getLoophausHome } from "../lib/paths.js";
+import { getGlobalBinaryPath, runCommand } from "../lib/runtime.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PROJECT_ROOT = resolve(__dirname, "..");
@@ -163,7 +165,7 @@ async function runInstall() {
     const { getPackageVersion } = await import("../lib/paths.js");
     const version = getPackageVersion();
     const quiet = args.includes("--quiet");
-    const loophausDir = join(process.env.HOME || "~", ".loophaus");
+    const loophausDir = getLoophausHome();
     const welcomePath = join(loophausDir, ".welcome-seen");
     let targets = [];
     if (host) {
@@ -763,9 +765,6 @@ async function runUpdateCheck() {
 async function runUpgrade() {
     const { getPackageVersion } = await import("../lib/paths.js");
     const { checkForUpdate } = await import("../core/update-checker.js");
-    const { execFile: ef } = await import("node:child_process");
-    const { promisify } = await import("node:util");
-    const execFileAsync = promisify(ef);
     const current = getPackageVersion();
     const result = await checkForUpdate(current);
     if (result.status === "up_to_date") {
@@ -779,12 +778,14 @@ async function runUpgrade() {
     console.log(`Upgrading loophaus: v${result.current} → v${result.latest}`);
     const s = spinner("Installing...");
     try {
-        await execFileAsync("npm", ["install", "-g", `@graypark/loophaus@${result.latest}`], { timeout: 120_000 });
+        await runCommand("npm", ["install", "-g", `@graypark/loophaus@${result.latest}`], { timeout: 120_000 });
         s.stop();
         console.log(`\u2714 Installed v${result.latest}`);
         const s2 = spinner("Reinstalling plugins...");
         try {
-            await execFileAsync("loophaus", ["install", "--force"], { timeout: 60_000 });
+            const { stdout: prefixStdout } = await runCommand("npm", ["prefix", "-g"], { timeout: 30_000 });
+            const globalLoophaus = getGlobalBinaryPath(prefixStdout.trim(), "loophaus");
+            await runCommand(globalLoophaus, ["install", "--force"], { timeout: 60_000 });
             s2.stop();
             console.log("\u2714 Plugins reinstalled");
         }

package/dist/commands/cancel-ralph.md

@@ -1,11 +1,6 @@
 ---
 description: "Cancel active Ralph Loop"
-allowed-tools:
-  [
-    "Bash(test -f .claude/ralph-loop.local.md:*)",
-    "Bash(rm .claude/ralph-loop.local.md)",
-    "Read(.claude/ralph-loop.local.md)",
-  ]
+allowed-tools: ["Bash", "Read"]
 hide-from-slash-command-tool: "true"
 ---
 
@@ -13,11 +8,11 @@ hide-from-slash-command-tool: "true"
 
 To cancel the Ralph loop:
 
-1. Check if `.claude/ralph-loop.local.md` exists using Bash: `test -f .claude/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"`
+1. Check if `.claude/ralph-loop.local.md` exists using a cross-platform Node command.
 
 2. **If NOT_FOUND**: Say "No active Ralph loop found."
 
 3. **If EXISTS**:
    - Read `.claude/ralph-loop.local.md` to get the current iteration number from the `iteration:` field
-   - Remove the file using Bash: `rm .claude/ralph-loop.local.md`
+   - Remove the file using a cross-platform Node file command
    - Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value

package/dist/commands/loop-plan.md

@@ -13,13 +13,9 @@ The user runs `/loop-plan` once and gets a single merged branch with all work do
 
 ## Pre-flight: Update Check
 
-Run this silently before starting:
+Run `loophaus update-check` silently before starting.
 
-```bash
-_UPDATE=$(loophaus update-check 2>/dev/null | grep "UPGRADE_AVAILABLE" || true)
-```
-
-If `_UPDATE` contains `UPGRADE_AVAILABLE`:
+If the command reports an available update:
 1. Show: `loophaus update available: v{current} → v{latest}`
 2. Ask user:
    - **A) Upgrade now** → run `loophaus upgrade`, then continue
@@ -30,7 +26,7 @@ If `_UPDATE` contains `UPGRADE_AVAILABLE`:
 If auto-upgrade is enabled (`loophaus config get autoUpgrade` returns `true`):
 - Skip prompt, run `loophaus upgrade` silently, continue.
 
-If no update or check fails: continue silently (never block the user).
+If no update is available or the check fails: continue silently and never block the user.
 
 ## Pre-flight: Skill Routing Check
 

package/dist/commands/loop-stop.md

@@ -1,29 +1,21 @@
 ---
 description: "Stop active loop"
-allowed-tools:
-  [
-    "Bash(test -f .loophaus/state.json:*)",
-    "Bash(rm .loophaus/state.json)",
-    "Read(.loophaus/state.json)",
-    "Bash(test -f .claude/ralph-loop.local.md:*)",
-    "Bash(rm .claude/ralph-loop.local.md)",
-    "Read(.claude/ralph-loop.local.md)",
-  ]
+allowed-tools: ["Bash", "Read"]
 ---
 
 # /loop-stop — Stop Active Loop
 
-1. Check if `.loophaus/state.json` exists: `test -f .loophaus/state.json && echo "EXISTS" || echo "NOT_FOUND"`
-   - If not found, also check legacy path: `test -f .claude/ralph-loop.local.md && echo "LEGACY" || echo "NOT_FOUND"`
+1. Check if `.loophaus/state.json` exists using a cross-platform Node command.
+   - If not found, also check legacy path `.claude/ralph-loop.local.md`.
 
 2. **If NOT_FOUND** on both: Say "No active loop found."
 
 3. **If EXISTS** (.loophaus/state.json):
    - Read the file to get `currentIteration`
-   - Remove it: `rm .loophaus/state.json`
+   - Remove it with a cross-platform Node file command
    - Report: "Stopped loop at iteration N."
 
 4. **If LEGACY** (.claude/ralph-loop.local.md):
    - Read it to get the iteration field
-   - Remove it: `rm .claude/ralph-loop.local.md`
+   - Remove it with a cross-platform Node file command
    - Report: "Stopped loop at iteration N. (migrated from legacy path)"

package/dist/commands/loop.md

@@ -1,26 +1,24 @@
 ---
 description: "Start iterative dev loop"
 argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
-allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
+allowed-tools: ["Bash"]
 ---
 
 # /loop — Start Iterative Dev Loop
 
 ## Pre-flight
 
-```bash
-_UPDATE=$(loophaus update-check 2>/dev/null | grep "UPGRADE_AVAILABLE" || true)
-```
-If update available and autoUpgrade enabled: run `loophaus upgrade` silently.
-If update available and not auto: show one-line notice `loophaus v{new} available. Run: loophaus upgrade`.
-Otherwise: continue silently.
+Run `loophaus update-check` quietly before starting.
+If it reports an available update and auto-upgrade is enabled, run `loophaus upgrade` and continue.
+If it reports an available update and auto-upgrade is disabled, show one-line notice: `loophaus update available. Run: loophaus upgrade`.
+If the check fails or no update is available, continue silently.
 
 ---
 
 Execute the setup script to initialize the loop:
 
 ```!
-"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
+node "${CLAUDE_PLUGIN_ROOT}/scripts/setup-loop.mjs" $ARGUMENTS
 ```
 
 Work on the task. When you try to exit, the stop hook feeds the SAME PROMPT back for the next iteration. Your previous work persists in files and git history.

package/dist/commands/ralph-loop.md

@@ -1,7 +1,7 @@
 ---
 description: "Start Ralph Loop in current session"
 argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
-allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
+allowed-tools: ["Bash"]
 hide-from-slash-command-tool: "true"
 ---
 
@@ -10,7 +10,7 @@ hide-from-slash-command-tool: "true"
 Execute the setup script to initialize the Ralph loop:
 
 ```!
-"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
+node "${CLAUDE_PLUGIN_ROOT}/scripts/setup-loop.mjs" $ARGUMENTS
 ```
 
 Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.

package/dist/core/benchmark.js

@@ -1,10 +1,23 @@
 // core/benchmark.ts
 // Project-level quality measurement (autoresearch pattern: val_bpb → project score)
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { readFile, appendFile, mkdir, stat } from "node:fs/promises";
+import { readFile, appendFile, mkdir, readdir, stat } from "node:fs/promises";
 import { join, dirname } from "node:path";
-const execFileAsync = promisify(execFile);
+import { runCommand } from "../lib/runtime.js";
+async function getDirectorySizeBytes(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    let total = 0;
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            total += await getDirectorySizeBytes(fullPath);
+            continue;
+        }
+        if (entry.isFile()) {
+            total += (await stat(fullPath)).size;
+        }
+    }
+    return total;
+}
 export function scoreBenchmark(metrics) {
     const breakdown = {};
     // Tests: 0-10 based on pass rate
@@ -51,7 +64,7 @@ export async function runBenchmark(cwd) {
     // 1. Tests
     const testStart = Date.now();
     try {
-        const { stdout } = await execFileAsync("npx", ["vitest", "run", "--reporter=json"], { cwd: dir, timeout: 120_000 });
+        const { stdout } = await runCommand("npx", ["vitest", "run", "--reporter=json"], { cwd: dir, timeout: 120_000 });
         metrics.testTimeMs = Date.now() - testStart;
         try {
             const json = JSON.parse(stdout);
@@ -72,7 +85,7 @@ export async function runBenchmark(cwd) {
     }
     catch (err) {
         metrics.testTimeMs = Date.now() - testStart;
-        const output = err.stdout || "";
+        const output = err.stdout || err.stderr || "";
         const passMatch = output.match(/(\d+) passed/);
         if (passMatch)
             metrics.testsPassed = parseInt(passMatch[1]);
@@ -83,7 +96,7 @@ export async function runBenchmark(cwd) {
     }
     // 2. Typecheck
     try {
-        await execFileAsync("npx", ["tsc", "--noEmit"], { cwd: dir, timeout: 60_000 });
+        await runCommand("npx", ["tsc", "--noEmit"], { cwd: dir, timeout: 60_000 });
         metrics.typecheckErrors = 0;
     }
     catch (err) {
@@ -93,7 +106,7 @@ export async function runBenchmark(cwd) {
     }
     // 3. Build
     try {
-        await execFileAsync("npm", ["run", "build"], { cwd: dir, timeout: 60_000 });
+        await runCommand("npm", ["run", "build"], { cwd: dir, timeout: 60_000 });
         metrics.buildSuccess = true;
     }
     catch {
@@ -109,7 +122,7 @@ export async function runBenchmark(cwd) {
     catch {
         // Run coverage if summary doesn't exist
         try {
-            await execFileAsync("npx", ["vitest", "run", "--coverage"], { cwd: dir, timeout: 120_000 });
+            await runCommand("npx", ["vitest", "run", "--coverage"], { cwd: dir, timeout: 120_000 });
             const summaryPath = join(dir, "coverage", "coverage-summary.json");
             const raw = await readFile(summaryPath, "utf-8");
             const summary = JSON.parse(raw);
@@ -124,9 +137,7 @@ export async function runBenchmark(cwd) {
         const distDir = join(dir, "dist");
         const s = await stat(distDir);
         if (s.isDirectory()) {
-            const { stdout } = await execFileAsync("du", ["-sk", distDir], { timeout: 10_000 });
-            const match = stdout.match(/^(\d+)/);
-            metrics.pkgSizeKb = match ? parseInt(match[1]) : 0;
+            metrics.pkgSizeKb = Math.ceil((await getDirectorySizeBytes(distDir)) / 1024);
         }
     }
     catch {
@@ -143,7 +154,7 @@ export async function logBenchmark(result, cwd) {
     await mkdir(dirname(benchPath), { recursive: true });
     let commitHash = "unknown";
     try {
-        const { stdout } = await execFileAsync("git", ["rev-parse", "--short", "HEAD"], { timeout: 5_000 });
+        const { stdout } = await runCommand("git", ["rev-parse", "--short", "HEAD"], { timeout: 5_000 });
         commitHash = stdout.trim();
     }
     catch { /* not in git */ }
@@ -182,7 +193,7 @@ export async function readBenchmarkHistory(cwd) {
     const benchPath = getBenchmarkPath(cwd);
     try {
         const raw = await readFile(benchPath, "utf-8");
-        const lines = raw.trim().split("\n").slice(1); // skip header
+        const lines = raw.trim().split(/\r?\n/).slice(1); // skip header
         return lines.map(line => {
             const cols = line.split("\t");
             return {

package/dist/core/quality-scorer.js

@@ -1,10 +1,8 @@
 // core/quality-scorer.ts
 // Quality scoring for story implementations (autoresearch pattern: val_bpb -> quality score)
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
-const execFileAsync = promisify(execFile);
+import { runCommand, runShellCommand } from "../lib/runtime.js";
 const CRITERIA = {
     tests: { weight: 3, max: 10 },
     typecheck: { weight: 2, max: 10 },
@@ -33,9 +31,10 @@ export function scoreStory(results) {
 }
 export async function evaluateStory(storyId, cwd, config = {}) {
     const results = {};
+    const splitLines = (value) => value.split(/\r?\n/);
     if (config.testCommand) {
         try {
-            await execFileAsync("sh", ["-c", config.testCommand], { cwd, timeout: 120_000 });
+            await runShellCommand(config.testCommand, { cwd, timeout: 120_000 });
             results.tests = 10;
         }
         catch {
@@ -44,27 +43,29 @@ export async function evaluateStory(storyId, cwd, config = {}) {
     }
     if (config.typecheckCommand) {
         try {
-            await execFileAsync("sh", ["-c", config.typecheckCommand], { cwd, timeout: 60_000 });
+            await runShellCommand(config.typecheckCommand, { cwd, timeout: 60_000 });
             results.typecheck = 10;
         }
         catch (err) {
-            const errorCount = (err.stdout || "").split("\n").filter(l => l.includes("error")).length;
+            const output = err.stdout || err.stderr || "";
+            const errorCount = splitLines(output).filter(line => line.includes("error")).length;
             results.typecheck = Math.max(0, 10 - errorCount);
         }
     }
     if (config.lintCommand) {
         try {
-            await execFileAsync("sh", ["-c", config.lintCommand], { cwd, timeout: 60_000 });
+            await runShellCommand(config.lintCommand, { cwd, timeout: 60_000 });
             results.lint = 10;
         }
         catch (err) {
-            const warnings = (err.stdout || "").split("\n").filter(l => l.includes("warning") || l.includes("error")).length;
+            const output = err.stdout || err.stderr || "";
+            const warnings = splitLines(output).filter(line => line.includes("warning") || line.includes("error")).length;
             results.lint = Math.max(0, 10 - warnings);
         }
     }
     if (config.verifyScript) {
         try {
-            await execFileAsync("sh", ["-c", config.verifyScript], { cwd, timeout: 60_000 });
+            await runShellCommand(config.verifyScript, { cwd, timeout: 60_000 });
             results.verify = 10;
         }
         catch {
@@ -72,8 +73,8 @@ export async function evaluateStory(storyId, cwd, config = {}) {
         }
     }
     try {
-        const { stdout } = await execFileAsync("git", ["diff", "--stat", "HEAD~1"], { cwd, timeout: 10_000 });
-        const lines = stdout.trim().split("\n");
+        const { stdout } = await runCommand("git", ["diff", "--stat", "HEAD~1"], { cwd, timeout: 10_000 });
+        const lines = stdout.trim().split(/\r?\n/);
         const lastLine = lines[lines.length - 1] || "";
         const match = lastLine.match(/(\d+) insertion.+?(\d+) deletion/);
         if (match) {
@@ -115,7 +116,7 @@ export async function readResults(cwd) {
     const tsvPath = join(cwd || process.cwd(), ".loophaus", "results.tsv");
     try {
         const raw = await readFile(tsvPath, "utf-8");
-        const lines = raw.trim().split("\n").slice(1);
+        const lines = raw.trim().split(/\r?\n/).slice(1);
         return lines.map(line => {
             const [storyId, attempt, score, status, description, commit] = line.split("\t");
             return { storyId, attempt: parseInt(attempt), score: parseInt(score), status, description, commit };

package/dist/core/update-checker.js

@@ -1,8 +1,9 @@
 // core/update-checker.ts
 // npm registry version check with cache + snooze (gstack-style)
 import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { get } from "node:https";
+import { getLoophausHome } from "../lib/paths.js";
 const REGISTRY_URL = "https://registry.npmjs.org/@graypark/loophaus/latest";
 const FETCH_TIMEOUT_MS = 5_000;
 // Cache TTL in minutes
@@ -11,7 +12,7 @@ const TTL_UPGRADE_AVAILABLE = 720;
 // Snooze durations in hours
 const SNOOZE_HOURS = [24, 48, 168]; // level 1, 2, 3+
 function getLoophausDir(cwd) {
-    return join(cwd || process.env.HOME || "~", ".loophaus");
+    return getLoophausHome(cwd);
 }
 function getCachePath(cwd) {
     return join(getLoophausDir(cwd), "update-cache.json");
@@ -60,7 +61,7 @@ async function readJson(path) {
     }
 }
 async function writeJson(path, data) {
-    await mkdir(join(path, ".."), { recursive: true });
+    await mkdir(dirname(path), { recursive: true });
     await writeFile(path, JSON.stringify(data, null, 2), "utf-8");
 }
 async function fetchLatestVersion() {

package/dist/core/worktree.js

@@ -3,7 +3,7 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { mkdir, access } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 const execFileAsync = promisify(execFile);
 async function fileExists(p) {
     try {
@@ -72,7 +72,7 @@ export async function listWorktrees() {
         const { stdout } = await execFileAsync("git", ["worktree", "list", "--porcelain"]);
         const entries = [];
         let current = {};
-        for (const line of stdout.split("\n")) {
+        for (const line of stdout.split(/\r?\n/)) {
             if (line.startsWith("worktree ")) {
                 if (current.path)
                     entries.push(current);
@@ -95,7 +95,7 @@ export async function listWorktrees() {
         }
         const loophausDir = join(root, ".loophaus", "worktrees");
         return entries.filter(e => e.path && e.path.startsWith(loophausDir)).map(e => ({
-            name: e.path.split("/").pop(),
+            name: basename(e.path),
             path: e.path,
             branch: e.branch || "",
             head: e.head || "",

package/dist/hooks/stop-hook.mjs

@@ -5,12 +5,10 @@ import { getLastAssistantText, hasPendingStories } from "../core/io-helpers.js";
 import { read as readState, write as writeState } from "../store/state-store.js";
 import { logEvents } from "../core/event-logger.js";
 import { join } from "node:path";
+import { runShellCommand } from "../lib/runtime.js";
 
 async function runStoryTests(cwd) {
   const { readFile } = await import("node:fs/promises");
-  const { execFile } = await import("node:child_process");
-  const { promisify } = await import("node:util");
-  const execFileAsync = promisify(execFile);
   const prdPath = join(cwd, "prd.json");
 
   try {
@@ -21,10 +19,10 @@ async function runStoryTests(cwd) {
     for (const story of prd.userStories) {
       if (!story.testCommand || story.passes) continue;
       try {
-        await execFileAsync("sh", ["-c", story.testCommand], { cwd, timeout: 60_000 });
+        await runShellCommand(story.testCommand, { cwd, timeout: 60_000 });
         results.push({ storyId: story.id, passed: true });
       } catch (err) {
-        results.push({ storyId: story.id, passed: false, error: err.message });
+        results.push({ storyId: story.id, passed: false, error: err.stderr || err.message });
       }
     }
     return results;
@@ -55,10 +53,7 @@ async function main() {
   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 });
+      const { stdout: vOut } = await runShellCommand(state.verifyScript, { cwd, timeout: 30_000 });
       verifyResult = { passed: true, output: vOut.trim() };
     } catch (err) {
       verifyResult = { passed: false, output: err.stderr || err.message };

package/dist/lib/paths.d.ts

@@ -1,5 +1,6 @@
 export declare function getPackageVersion(): string;
 export declare function isWindows(): boolean;
+export declare function getLoophausHome(homeDir?: string): string;
 export declare function getCodexHome(): string;
 export declare function getAgentsHome(): string;
 export declare function getAgentsSkillsDir(): string;

package/dist/lib/paths.js

@@ -20,6 +20,9 @@ export function getPackageVersion() {
 export function isWindows() {
     return process.platform === "win32";
 }
+export function getLoophausHome(homeDir) {
+    return join(homeDir || homedir(), ".loophaus");
+}
 // --- Codex CLI paths (legacy ~/.codex + new ~/.agents) ---
 export function getCodexHome() {
     if (process.env.CODEX_HOME) {

package/dist/lib/runtime.d.ts

@@ -0,0 +1,21 @@
+import type { ExecException } from "node:child_process";
+export interface CommandOptions {
+    cwd?: string;
+    timeout?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export interface CommandResult {
+    stdout: string;
+    stderr: string;
+}
+export interface CommandError extends ExecException {
+    stdout?: string;
+    stderr?: string;
+}
+export declare function getDefaultShell(platform?: NodeJS.Platform): string;
+export declare function resolvePlatformCommand(command: string, platform?: NodeJS.Platform): string;
+export declare function requiresShellExecution(command: string, platform?: NodeJS.Platform): boolean;
+export declare function getGlobalBinDir(prefix: string, platform?: NodeJS.Platform): string;
+export declare function getGlobalBinaryPath(prefix: string, binaryName: string, platform?: NodeJS.Platform): string;
+export declare function runCommand(command: string, args?: string[], options?: CommandOptions): Promise<CommandResult>;
+export declare function runShellCommand(command: string, options?: CommandOptions): Promise<CommandResult>;

package/dist/lib/runtime.js

@@ -0,0 +1,77 @@
+import { exec, execFile } from "node:child_process";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { isWindows } from "./paths.js";
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+const WINDOWS_BATCH_COMMANDS = new Set(["loophaus", "npm", "npx"]);
+export function getDefaultShell(platform = process.platform) {
+    if (platform === "win32") {
+        return process.env.ComSpec || "cmd.exe";
+    }
+    return process.env.SHELL || "/bin/sh";
+}
+export function resolvePlatformCommand(command, platform = process.platform) {
+    if (platform !== "win32")
+        return command;
+    if (/[/\\]/.test(command) || /\.[A-Za-z0-9]+$/.test(command))
+        return command;
+    if (WINDOWS_BATCH_COMMANDS.has(command))
+        return `${command}.cmd`;
+    return command;
+}
+export function requiresShellExecution(command, platform = process.platform) {
+    if (platform !== "win32")
+        return false;
+    return /\.(cmd|bat)$/i.test(command);
+}
+export function getGlobalBinDir(prefix, platform = process.platform) {
+    return platform === "win32" ? prefix : join(prefix, "bin");
+}
+export function getGlobalBinaryPath(prefix, binaryName, platform = process.platform) {
+    const suffix = platform === "win32" ? ".cmd" : "";
+    return join(getGlobalBinDir(prefix, platform), `${binaryName}${suffix}`);
+}
+function createBaseExecOptions(options) {
+    return {
+        cwd: options.cwd,
+        env: options.env,
+        timeout: options.timeout,
+        encoding: "utf8",
+        windowsHide: isWindows(),
+    };
+}
+function quoteWindowsArg(value) {
+    if (value.length === 0)
+        return "\"\"";
+    if (!/[\s"&|<>^()]/.test(value))
+        return value;
+    return `"${value.replace(/"/g, "\"\"")}"`;
+}
+function buildShellCommand(command, args) {
+    if (!isWindows()) {
+        return [command, ...args].map((part) => {
+            if (/^[A-Za-z0-9_./:=+-]+$/.test(part))
+                return part;
+            return `'${part.replace(/'/g, `'\\''`)}'`;
+        }).join(" ");
+    }
+    return [command, ...args].map(quoteWindowsArg).join(" ");
+}
+export async function runCommand(command, args = [], options = {}) {
+    const resolved = resolvePlatformCommand(command);
+    const execOptions = createBaseExecOptions(options);
+    if (requiresShellExecution(resolved)) {
+        return execAsync(buildShellCommand(resolved, args), {
+            ...execOptions,
+            shell: getDefaultShell(),
+        });
+    }
+    return execFileAsync(resolved, args, execOptions);
+}
+export async function runShellCommand(command, options = {}) {
+    return execAsync(command, {
+        ...createBaseExecOptions(options),
+        shell: getDefaultShell(),
+    });
+}

package/dist/package.json

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

package/dist/platforms/claude-code/installer.mjs

@@ -71,6 +71,8 @@ export async function install({ dryRun = false, force = false } = {}) {
   if (!dryRun) {
     const sh = join(cacheDir, "scripts", "setup-ralph-loop.sh");
     if (await fileExists(sh)) await chmod(sh, 0o755);
+    const nodeScript = join(cacheDir, "scripts", "setup-loop.mjs");
+    if (await fileExists(nodeScript)) await chmod(nodeScript, 0o755);
   }
 
   // Step 2: Register marketplace

package/dist/platforms/codex-cli/installer.mjs

@@ -185,7 +185,7 @@ export async function install({ dryRun = false, force = false, local = false } =
 
   // Step 2: Copy files
   console.log(`[2/${totalSteps}] Copying plugin files...`);
-  for (const dir of ["hooks", "codex/commands", "lib", "core", "store"]) {
+  for (const dir of ["hooks", "codex/commands", "scripts", "lib", "core", "store"]) {
     const src = join(PROJECT_ROOT, dir);
     if (!(await fileExists(src))) continue;
     const destDir = dir === "codex/commands" ? "commands" : dir;

package/dist/scripts/setup-loop.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+import { access } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function loadStateStore() {
+  const candidates = [
+    join(__dirname, "..", "store", "state-store.js"),
+    join(__dirname, "..", "dist", "store", "state-store.js"),
+  ];
+
+  for (const candidate of candidates) {
+    if (await fileExists(candidate)) {
+      return import(pathToFileURL(candidate).href);
+    }
+  }
+
+  throw new Error("Could not locate state-store.js");
+}
+
+function printHelp() {
+  console.log(`loophaus — Iterative coding loop
+
+USAGE:
+  /loop [PROMPT...] [OPTIONS]
+
+ARGUMENTS:
+  PROMPT...    Initial prompt to start the loop
+
+OPTIONS:
+  --max-iterations <n>           Maximum iterations before auto-stop (default: unlimited)
+  --completion-promise <text>    Promise phrase for explicit completion
+  -h, --help                     Show this help message`);
+}
+
+function parseArgs(argv) {
+  const promptParts = [];
+  let maxIterations = 0;
+  let completionPromise = "";
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      printHelp();
+      process.exit(0);
+    }
+    if (arg === "--max-iterations") {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error("--max-iterations requires a number argument");
+      }
+      if (!/^\d+$/.test(value)) {
+        throw new Error(`--max-iterations must be a positive integer or 0, got: ${value}`);
+      }
+      maxIterations = Number.parseInt(value, 10);
+      i += 1;
+      continue;
+    }
+    if (arg === "--completion-promise") {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error("--completion-promise requires a text argument");
+      }
+      completionPromise = value;
+      i += 1;
+      continue;
+    }
+    promptParts.push(arg);
+  }
+
+  const prompt = promptParts.join(" ").trim();
+  if (!prompt) {
+    throw new Error("No prompt provided");
+  }
+
+  return { prompt, maxIterations, completionPromise };
+}
+
+async function main() {
+  const { readState, writeState } = await loadStateStore();
+  const { prompt, maxIterations, completionPromise } = parseArgs(process.argv.slice(2));
+  const existingState = await readState(process.cwd());
+  const sessionId =
+    process.env.CLAUDE_CODE_SESSION_ID ||
+    process.env.CODEX_SESSION_ID ||
+    process.env.SESSION_ID ||
+    "";
+
+  await writeState({
+    ...existingState,
+    active: true,
+    prompt,
+    completionPromise,
+    maxIterations,
+    currentIteration: 0,
+    sessionId,
+    startedAt: new Date().toISOString(),
+  }, process.cwd());
+
+  console.log("Loop activated!");
+  console.log("");
+  console.log("Iteration: 1");
+  console.log(`Max iterations: ${maxIterations > 0 ? maxIterations : "unlimited"}`);
+  console.log(`Completion promise: ${completionPromise || "none (runs until stopped or max iterations)"}`);
+  console.log("");
+  console.log("The stop hook is now active. When you try to exit, the same prompt will be fed back.");
+  console.log("To cancel: /loop-stop");
+  console.log("To monitor: read .loophaus/state.json");
+  console.log("");
+  console.log(prompt);
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/hooks/stop-hook.mjs

@@ -5,12 +5,10 @@ import { getLastAssistantText, hasPendingStories } from "../core/io-helpers.js";
 import { read as readState, write as writeState } from "../store/state-store.js";
 import { logEvents } from "../core/event-logger.js";
 import { join } from "node:path";
+import { runShellCommand } from "../lib/runtime.js";
 
 async function runStoryTests(cwd) {
   const { readFile } = await import("node:fs/promises");
-  const { execFile } = await import("node:child_process");
-  const { promisify } = await import("node:util");
-  const execFileAsync = promisify(execFile);
   const prdPath = join(cwd, "prd.json");
 
   try {
@@ -21,10 +19,10 @@ async function runStoryTests(cwd) {
     for (const story of prd.userStories) {
       if (!story.testCommand || story.passes) continue;
       try {
-        await execFileAsync("sh", ["-c", story.testCommand], { cwd, timeout: 60_000 });
+        await runShellCommand(story.testCommand, { cwd, timeout: 60_000 });
         results.push({ storyId: story.id, passed: true });
       } catch (err) {
-        results.push({ storyId: story.id, passed: false, error: err.message });
+        results.push({ storyId: story.id, passed: false, error: err.stderr || err.message });
       }
     }
     return results;
@@ -55,10 +53,7 @@ async function main() {
   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 });
+      const { stdout: vOut } = await runShellCommand(state.verifyScript, { cwd, timeout: 30_000 });
       verifyResult = { passed: true, output: vOut.trim() };
     } catch (err) {
       verifyResult = { passed: false, output: err.stderr || err.message };

package/package.json

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

package/platforms/claude-code/installer.mjs

@@ -71,6 +71,8 @@ export async function install({ dryRun = false, force = false } = {}) {
   if (!dryRun) {
     const sh = join(cacheDir, "scripts", "setup-ralph-loop.sh");
     if (await fileExists(sh)) await chmod(sh, 0o755);
+    const nodeScript = join(cacheDir, "scripts", "setup-loop.mjs");
+    if (await fileExists(nodeScript)) await chmod(nodeScript, 0o755);
   }
 
   // Step 2: Register marketplace

package/platforms/codex-cli/installer.mjs

@@ -185,7 +185,7 @@ export async function install({ dryRun = false, force = false, local = false } =
 
   // Step 2: Copy files
   console.log(`[2/${totalSteps}] Copying plugin files...`);
-  for (const dir of ["hooks", "codex/commands", "lib", "core", "store"]) {
+  for (const dir of ["hooks", "codex/commands", "scripts", "lib", "core", "store"]) {
     const src = join(PROJECT_ROOT, dir);
     if (!(await fileExists(src))) continue;
     const destDir = dir === "codex/commands" ? "commands" : dir;

package/scripts/setup-loop.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+import { access } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function loadStateStore() {
+  const candidates = [
+    join(__dirname, "..", "store", "state-store.js"),
+    join(__dirname, "..", "dist", "store", "state-store.js"),
+  ];
+
+  for (const candidate of candidates) {
+    if (await fileExists(candidate)) {
+      return import(pathToFileURL(candidate).href);
+    }
+  }
+
+  throw new Error("Could not locate state-store.js");
+}
+
+function printHelp() {
+  console.log(`loophaus — Iterative coding loop
+
+USAGE:
+  /loop [PROMPT...] [OPTIONS]
+
+ARGUMENTS:
+  PROMPT...    Initial prompt to start the loop
+
+OPTIONS:
+  --max-iterations <n>           Maximum iterations before auto-stop (default: unlimited)
+  --completion-promise <text>    Promise phrase for explicit completion
+  -h, --help                     Show this help message`);
+}
+
+function parseArgs(argv) {
+  const promptParts = [];
+  let maxIterations = 0;
+  let completionPromise = "";
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      printHelp();
+      process.exit(0);
+    }
+    if (arg === "--max-iterations") {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error("--max-iterations requires a number argument");
+      }
+      if (!/^\d+$/.test(value)) {
+        throw new Error(`--max-iterations must be a positive integer or 0, got: ${value}`);
+      }
+      maxIterations = Number.parseInt(value, 10);
+      i += 1;
+      continue;
+    }
+    if (arg === "--completion-promise") {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error("--completion-promise requires a text argument");
+      }
+      completionPromise = value;
+      i += 1;
+      continue;
+    }
+    promptParts.push(arg);
+  }
+
+  const prompt = promptParts.join(" ").trim();
+  if (!prompt) {
+    throw new Error("No prompt provided");
+  }
+
+  return { prompt, maxIterations, completionPromise };
+}
+
+async function main() {
+  const { readState, writeState } = await loadStateStore();
+  const { prompt, maxIterations, completionPromise } = parseArgs(process.argv.slice(2));
+  const existingState = await readState(process.cwd());
+  const sessionId =
+    process.env.CLAUDE_CODE_SESSION_ID ||
+    process.env.CODEX_SESSION_ID ||
+    process.env.SESSION_ID ||
+    "";
+
+  await writeState({
+    ...existingState,
+    active: true,
+    prompt,
+    completionPromise,
+    maxIterations,
+    currentIteration: 0,
+    sessionId,
+    startedAt: new Date().toISOString(),
+  }, process.cwd());
+
+  console.log("Loop activated!");
+  console.log("");
+  console.log("Iteration: 1");
+  console.log(`Max iterations: ${maxIterations > 0 ? maxIterations : "unlimited"}`);
+  console.log(`Completion promise: ${completionPromise || "none (runs until stopped or max iterations)"}`);
+  console.log("");
+  console.log("The stop hook is now active. When you try to exit, the same prompt will be fed back.");
+  console.log("To cancel: /loop-stop");
+  console.log("To monitor: read .loophaus/state.json");
+  console.log("");
+  console.log(prompt);
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});