@jhlee0619/codexloop 0.1.0

package/scripts/loop-companion.mjs

@@ -0,0 +1,849 @@
+#!/usr/bin/env node
+// CodexLoop companion script.
+//
+// Single entry point dispatched by all slash commands (and, for background
+// loops, re-entered as the detached worker via the internal `loop-worker`
+// verb). Verbs:
+//
+//   start        — initialize a new loop and run it (foreground or background)
+//   iterate      — run exactly one iteration synchronously
+//   status       — show current state (read-only)
+//   stop         — signal a running worker (SIGTERM, or SIGKILL with --force)
+//   result       — dump full iteration history + final diff hints
+//   loop-worker  — internal: the detached worker invoked by /cloop:start --background
+//
+// All verbs honor `-C, --cwd <dir>` to override the target repository root.
+//
+// This file mirrors the structure of codex-plugin-cc's scripts/codex-companion.mjs
+// verb dispatch pattern but owns all code directly — no cross-plugin imports.
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import {
+  normalizeArgv,
+  parseArgs,
+  parseDuration,
+  parseInteger
+} from "./lib/args.mjs";
+import {
+  gitHeadSha,
+  requireGitRepository
+} from "./lib/workspace.mjs";
+import {
+  acquireLock,
+  computeGoalHash,
+  DEFAULT_MODEL,
+  DEFAULT_REASONING_EFFORT,
+  defaultState,
+  ensureGitignore,
+  ensureLoopDir,
+  generateLoopId,
+  getLoopPaths,
+  loadState,
+  LoopLockError,
+  MODEL_ALIASES,
+  normalizeModelName,
+  normalizeReasoningEffort,
+  readIterationFile,
+  readLock,
+  readPidFile,
+  releaseLock,
+  removePidFile,
+  saveState,
+  VALID_REASONING_EFFORTS,
+  writePidFile
+} from "./lib/state.mjs";
+import { runIteration } from "./lib/iteration.mjs";
+import { checkCodexAvailable } from "./lib/codex-exec.mjs";
+import { checkStopping } from "./lib/convergence.mjs";
+import {
+  isProcessAlive,
+  runCommand,
+  sleep,
+  spawnDetached,
+  terminateProcess
+} from "./lib/process.mjs";
+import {
+  renderIterationReport,
+  renderResultReport,
+  renderStatusReport
+} from "./lib/render.mjs";
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+
+const USAGE = [
+  "Usage:",
+  "  cloop start   [--wait|--background] [--goal <text>] [--task-file <path>]",
+  "                [--max-iter N] [--max-time <dur>] [--max-calls N]",
+  "                [--dry-run] [--model <m>] [--effort <e>] [--nproposals N]",
+  "                [--test-cmd <cmd>] [--lint-cmd <cmd>] [--type-cmd <cmd>]",
+  "                [-C <dir>]",
+  "  cloop iterate [--dry-run] [--skip-apply] [--model <m>] [--effort <e>] [-C <dir>]",
+  "  cloop status  [--json] [-C <dir>]",
+  "  cloop stop    [--force] [-C <dir>]",
+  "  cloop result  [--iteration N] [--json] [--diff] [-C <dir>]",
+  "  cloop model   [<model>] [--effort <e>] [--list] [--clear] [--json] [-C <dir>]",
+  "",
+  "  (internal)  cloop loop-worker --loop-id <id> [-C <dir>]",
+  "",
+  `Defaults: model=${DEFAULT_MODEL}, reasoning effort=${DEFAULT_REASONING_EFFORT}.`,
+  `Valid reasoning efforts: ${VALID_REASONING_EFFORTS.join(", ")}.`,
+  "",
+  "Inside Claude Code you can also invoke these as /cloop:start, /cloop:iterate,",
+  "/cloop:status, /cloop:stop, /cloop:result, /cloop:model."
+].join("\n");
+
+const VALUE_OPTIONS = [
+  "goal", "task-file", "max-iter", "max-time", "max-calls",
+  "model", "effort", "nproposals", "test-cmd", "lint-cmd", "type-cmd",
+  "cwd", "loop-id", "iteration"
+];
+const BOOLEAN_OPTIONS = [
+  "wait", "background", "dry-run", "skip-apply",
+  "force", "json", "diff", "list", "clear",
+  // `yes` is a UX hint the slash command body uses to skip the approval
+  // dialog. The runtime itself ignores it — we just list it here so
+  // parseArgs accepts it without turning it into a positional.
+  "yes"
+];
+const ALIAS_MAP = { C: "cwd" };
+
+const VERBS = {
+  start: handleStart,
+  iterate: handleIterate,
+  status: handleStatus,
+  stop: handleStop,
+  result: handleResult,
+  model: handleModel,
+  "loop-worker": handleWorker
+};
+
+function parseCommonArgs(argv) {
+  return parseArgs(argv, {
+    valueOptions: VALUE_OPTIONS,
+    booleanOptions: BOOLEAN_OPTIONS,
+    aliasMap: ALIAS_MAP
+  });
+}
+
+function resolveCwd(options) {
+  return options.cwd ? path.resolve(process.cwd(), options.cwd) : process.cwd();
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function printError(msg) {
+  process.stderr.write(`${msg}\n`);
+}
+
+async function main() {
+  const [verb, ...rawArgv] = process.argv.slice(2);
+
+  if (!verb || verb === "--help" || verb === "-h") {
+    process.stdout.write(`${USAGE}\n`);
+    return verb ? 0 : 1;
+  }
+
+  const handler = VERBS[verb];
+  if (!handler) {
+    printError(`Unknown verb: ${verb}`);
+    printError(USAGE);
+    return 1;
+  }
+
+  try {
+    const argv = normalizeArgv(rawArgv);
+    const code = await handler(argv);
+    return typeof code === "number" ? code : 0;
+  } catch (err) {
+    if (err instanceof LoopLockError) {
+      printError(err.message);
+      return 2;
+    }
+    printError(`Error: ${err.message ?? err}`);
+    if (process.env.CODEXLOOP_DEBUG && err.stack) {
+      printError(err.stack);
+    }
+    return 1;
+  }
+}
+
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    printError(`Fatal: ${err.message ?? err}`);
+    if (err.stack) printError(err.stack);
+    process.exit(1);
+  }
+);
+
+// ── start ──────────────────────────────────────────────────────────
+async function handleStart(argv) {
+  const { options, positionals } = parseCommonArgs(argv);
+  const repoRoot = requireGitRepository(resolveCwd(options));
+
+  const availability = checkCodexAvailable({ cwd: repoRoot });
+  if (!availability.available) {
+    printError(`Codex CLI is not ready: ${availability.detail}`);
+    return 1;
+  }
+
+  const existingLock = readLock(repoRoot);
+  if (existingLock && isProcessAlive(existingLock.pid)) {
+    printError(
+      `A CodexLoop is already running (pid=${existingLock.pid}, loopId=${existingLock.loopId}). ` +
+        "Use /cloop:stop or /cloop:status before starting a new loop."
+    );
+    return 2;
+  }
+  if (existingLock) {
+    releaseLock(repoRoot);
+  }
+
+  const status = runCommand("git", ["status", "--porcelain"], { cwd: repoRoot });
+  if ((status.stdout || "").trim()) {
+    printError("Working tree is not clean. Commit or stash your changes before /cloop:start.");
+    printError(
+      status.stdout.trim().split("\n").slice(0, 10).join("\n")
+    );
+    return 1;
+  }
+
+  // Goal sources, in priority order:
+  //   1. --goal "<text>"  (explicit flag)
+  //   2. --task-file <path>  (read goal from a file)
+  //   3. positional tokens  (e.g. `cloop start "fix the bug"` or `cloop start fix the bug`)
+  //   4. error — runtime requires an explicit goal. (Claude Code's slash
+  //      command body runs an interview BEFORE hitting the runtime, so
+  //      users interacting via /cloop:start never see this error; it only
+  //      fires when somebody calls the CLI directly without a goal.)
+  let goalText = options.goal ? String(options.goal).trim() : "";
+  if (!goalText && options["task-file"]) {
+    const taskPath = path.resolve(repoRoot, options["task-file"]);
+    if (!fs.existsSync(taskPath)) {
+      printError(`Task file not found: ${taskPath}`);
+      return 1;
+    }
+    goalText = fs.readFileSync(taskPath, "utf8").trim();
+  }
+  if (!goalText && Array.isArray(positionals) && positionals.length > 0) {
+    // Join any free-form positional tokens. Works for both
+    // `cloop start "fix the bug"` (shell handed us 1 quoted token which
+    // splitRawArgumentString re-tokenizes on whitespace) and the
+    // multi-token `cloop start fix the bug` form. Either way, joining
+    // with space reproduces the original text.
+    goalText = positionals.join(" ").trim();
+  }
+  if (!goalText) {
+    printError(
+      'A goal is required. Pass --goal "<text>", --task-file <path>, or a free-form goal as the first positional argument (e.g. `cloop start "fix the failing test"`).'
+    );
+    return 1;
+  }
+
+  const state = defaultState();
+  state.loopId = generateLoopId();
+  state.mode = options["dry-run"] ? "dry-run" : options.background ? "background" : "interactive";
+  // model + reasoningEffort default to DEFAULT_MODEL / DEFAULT_REASONING_EFFORT
+  // via defaultState(); user-supplied --model / --effort override them here.
+  if (options.model !== undefined) {
+    state.model = normalizeModelName(options.model);
+  }
+  if (options.effort !== undefined) {
+    try {
+      state.reasoningEffort = normalizeReasoningEffort(options.effort);
+    } catch (err) {
+      printError(err.message);
+      return 1;
+    }
+  }
+  state.startedAt = nowIso();
+  state.goal.text = goalText;
+  state.goal.seedCommit = gitHeadSha(repoRoot);
+  state.goal.testCmd = options["test-cmd"] ?? null;
+  state.goal.lintCmd = options["lint-cmd"] ?? null;
+  state.goal.typeCmd = options["type-cmd"] ?? null;
+  state.goal.goalHash = computeGoalHash(state.goal);
+
+  if (options["max-iter"]) {
+    state.budget.maxIterations = parseInteger(options["max-iter"], {
+      name: "--max-iter",
+      min: 1,
+      max: 1000
+    });
+  }
+  if (options["max-time"]) {
+    state.budget.maxElapsedMs = parseDuration(options["max-time"]);
+  }
+  if (options["max-calls"]) {
+    state.budget.maxCodexCalls = parseInteger(options["max-calls"], {
+      name: "--max-calls",
+      min: 1
+    });
+  }
+
+  state.budget.consumed.startedAtMs = Date.now();
+  state.status = "queued";
+  state.pid = null;
+
+  ensureLoopDir(repoRoot);
+  const gi = ensureGitignore(repoRoot);
+  if (gi.added) {
+    process.stdout.write(`Added .loop/ to ${gi.path}\n`);
+  }
+  saveState(repoRoot, state);
+
+  const foreground = options.wait || !options.background;
+
+  if (!foreground) {
+    const loopPaths = getLoopPaths(repoRoot);
+    const pid = spawnDetached(
+      SCRIPT_PATH,
+      ["loop-worker", "--loop-id", state.loopId, "-C", repoRoot],
+      { cwd: repoRoot, logFile: loopPaths.log }
+    );
+    if (!pid) {
+      printError("Failed to spawn background worker.");
+      return 1;
+    }
+    process.stdout.write(
+      [
+        "CodexLoop started in background.",
+        `  loopId: ${state.loopId}`,
+        `  pid:    ${pid}`,
+        `  log:    ${loopPaths.log}`,
+        "Check status with /cloop:status.",
+        ""
+      ].join("\n")
+    );
+    return 0;
+  }
+
+  // Foreground mode: we ARE the worker.
+  try {
+    acquireLock(repoRoot, { pid: process.pid, loopId: state.loopId });
+  } catch (err) {
+    if (err instanceof LoopLockError) {
+      printError(err.message);
+      return 2;
+    }
+    throw err;
+  }
+  writePidFile(repoRoot, process.pid);
+
+  try {
+    const s2 = loadState(repoRoot);
+    s2.status = "running";
+    s2.pid = process.pid;
+    saveState(repoRoot, s2);
+
+    const runOpts = buildRunOptions(options);
+    await runLoop({ repoRoot, runOpts });
+
+    const final = loadState(repoRoot);
+    process.stdout.write(`${renderStatusReport(final)}\n`);
+    if (final.status === "completed") return 0;
+    if (final.status === "paused") return 0;
+    return 1;
+  } finally {
+    removePidFile(repoRoot);
+    releaseLock(repoRoot);
+  }
+}
+
+function buildRunOptions(options) {
+  const runOpts = {
+    dryRun: !!options["dry-run"],
+    skipApply: !!options["skip-apply"]
+  };
+  // Only set model / reasoningEffort when the user explicitly passed them,
+  // so the runtime falls back to the stored state.model / state.reasoningEffort.
+  if (options.model !== undefined) {
+    runOpts.model = normalizeModelName(options.model);
+  }
+  if (options.effort !== undefined) {
+    runOpts.reasoningEffort = normalizeReasoningEffort(options.effort);
+  }
+  if (options.nproposals) {
+    runOpts.nProposals = parseInteger(options.nproposals, {
+      name: "--nproposals",
+      min: 2,
+      max: 5
+    });
+  }
+  return runOpts;
+}
+
+// ── main run loop (shared by foreground start + background worker) ─
+async function runLoop({ repoRoot, runOpts }) {
+  let stopRequested = false;
+  const markStop = (signal) => {
+    stopRequested = true;
+    process.stdout.write(`\nCodexLoop: received ${signal}; stopping at next iteration boundary...\n`);
+  };
+  const onTerm = () => markStop("SIGTERM");
+  const onInt = () => markStop("SIGINT");
+  process.on("SIGTERM", onTerm);
+  process.on("SIGINT", onInt);
+
+  try {
+    while (!stopRequested) {
+      const state = loadState(repoRoot);
+      if (["completed", "paused", "failed", "cancelled"].includes(state.status)) {
+        break;
+      }
+
+      const stop = checkStopping(state);
+      if (stop.shouldStop) {
+        const finalState = loadState(repoRoot);
+        finalState.status = stop.reason === "goal-met" ? "completed" : "paused";
+        finalState.stopReason = stop.reason;
+        finalState.completedAt = nowIso();
+        saveState(repoRoot, finalState);
+        break;
+      }
+
+      try {
+        const { iteration } = await runIteration({ repoRoot, options: runOpts });
+        process.stdout.write(`${renderIterationReport(iteration)}\n\n`);
+        if (iteration.stopReason) {
+          break;
+        }
+      } catch (err) {
+        printError(`Iteration failed: ${err.message ?? err}`);
+        const s = loadState(repoRoot);
+        s.status = "failed";
+        s.error = {
+          kind: err.kind ?? err.name ?? "Error",
+          message: err.message ?? String(err)
+        };
+        s.completedAt = nowIso();
+        saveState(repoRoot, s);
+        return;
+      }
+    }
+
+    if (stopRequested) {
+      const s = loadState(repoRoot);
+      if (s.status === "running") {
+        s.status = "paused";
+        s.stopReason = s.stopReason ?? "user-stop";
+        s.completedAt = nowIso();
+        saveState(repoRoot, s);
+      }
+    }
+  } finally {
+    process.off("SIGTERM", onTerm);
+    process.off("SIGINT", onInt);
+  }
+}
+
+// ── iterate (foreground single-shot) ───────────────────────────────
+async function handleIterate(argv) {
+  const { options } = parseCommonArgs(argv);
+  const repoRoot = requireGitRepository(resolveCwd(options));
+
+  const state = loadState(repoRoot);
+  if (!state.loopId) {
+    printError("No active loop. Run /cloop:start first.");
+    return 1;
+  }
+  if (["completed", "failed", "cancelled"].includes(state.status)) {
+    printError(
+      `Loop is in terminal state: ${state.status}. Start a new loop with /cloop:start.`
+    );
+    return 1;
+  }
+
+  const lock = readLock(repoRoot);
+  if (lock && lock.pid !== process.pid && isProcessAlive(lock.pid)) {
+    printError(
+      `Another process (pid=${lock.pid}) is running the loop. Use /cloop:stop first to yield.`
+    );
+    return 2;
+  }
+
+  try {
+    acquireLock(repoRoot, { pid: process.pid, loopId: state.loopId });
+  } catch (err) {
+    if (err instanceof LoopLockError) {
+      printError(err.message);
+      return 2;
+    }
+    throw err;
+  }
+  writePidFile(repoRoot, process.pid);
+
+  try {
+    const runOpts = buildRunOptions(options);
+    const { iteration } = await runIteration({ repoRoot, options: runOpts });
+    process.stdout.write(`${renderIterationReport(iteration)}\n`);
+    return 0;
+  } catch (err) {
+    printError(`Iteration failed: ${err.message ?? err}`);
+    return 1;
+  } finally {
+    removePidFile(repoRoot);
+    releaseLock(repoRoot);
+  }
+}
+
+// ── status (read-only) ─────────────────────────────────────────────
+async function handleStatus(argv) {
+  const { options } = parseCommonArgs(argv);
+  const repoRoot = requireGitRepository(resolveCwd(options));
+  let state = loadState(repoRoot);
+
+  // Detect crashed worker: status says running but pid is dead.
+  if (state.status === "running" && state.pid && !isProcessAlive(state.pid)) {
+    state.status = "crashed";
+    state.error = state.error ?? { kind: "crash", message: `worker pid ${state.pid} is not alive` };
+    saveState(repoRoot, state);
+    releaseLock(repoRoot);
+    removePidFile(repoRoot);
+  }
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(state, null, 2)}\n`);
+    return 0;
+  }
+  process.stdout.write(`${renderStatusReport(state)}\n`);
+  return 0;
+}
+
+// ── stop (signal running worker) ───────────────────────────────────
+async function handleStop(argv) {
+  const { options } = parseCommonArgs(argv);
+  const repoRoot = requireGitRepository(resolveCwd(options));
+
+  const state = loadState(repoRoot);
+  const pid = state.pid ?? readPidFile(repoRoot);
+  if (!pid) {
+    process.stdout.write("No running CodexLoop found.\n");
+    return 0;
+  }
+
+  if (!isProcessAlive(pid)) {
+    const s = loadState(repoRoot);
+    if (s.status === "running") {
+      s.status = "crashed";
+      s.error = s.error ?? { kind: "crash", message: `stale pid ${pid}` };
+      saveState(repoRoot, s);
+    }
+    removePidFile(repoRoot);
+    releaseLock(repoRoot);
+    process.stdout.write(`No live worker (stale pid ${pid}). Cleaned up.\n`);
+    return 0;
+  }
+
+  if (options.force) {
+    terminateProcess(pid, "SIGKILL");
+    const s = loadState(repoRoot);
+    s.status = "cancelled";
+    s.stopReason = "user-stop-force";
+    s.completedAt = nowIso();
+    saveState(repoRoot, s);
+    removePidFile(repoRoot);
+    releaseLock(repoRoot);
+    process.stdout.write(`Sent SIGKILL to pid ${pid}. Loop marked cancelled.\n`);
+    return 0;
+  }
+
+  terminateProcess(pid, "SIGTERM");
+  process.stdout.write(`Sent SIGTERM to pid ${pid}. Waiting up to 60 s for graceful shutdown...\n`);
+
+  const deadline = Date.now() + 60_000;
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) break;
+    await sleep(500);
+  }
+
+  if (isProcessAlive(pid)) {
+    printError(
+      `Worker pid ${pid} did not exit within 60 s. Re-run '/cloop:stop --force' to SIGKILL.`
+    );
+    return 1;
+  }
+
+  const finalState = loadState(repoRoot);
+  if (finalState.status === "running") {
+    finalState.status = "paused";
+    finalState.stopReason = finalState.stopReason ?? "user-stop";
+    finalState.completedAt = nowIso();
+    saveState(repoRoot, finalState);
+  }
+  removePidFile(repoRoot);
+  releaseLock(repoRoot);
+  process.stdout.write(`Worker pid ${pid} stopped. Status: ${finalState.status}.\n`);
+  return 0;
+}
+
+// ── result (read-only) ─────────────────────────────────────────────
+async function handleResult(argv) {
+  const { options } = parseCommonArgs(argv);
+  const repoRoot = requireGitRepository(resolveCwd(options));
+  const state = loadState(repoRoot);
+
+  const fullIterations = (state.iterations ?? []).map((summary) => {
+    const full = readIterationFile(repoRoot, summary.index, { dryRun: summary.dryRun });
+    return full ?? summary;
+  });
+
+  const iterationIndex = options.iteration
+    ? parseInteger(options.iteration, { name: "--iteration", min: 1 })
+    : null;
+
+  if (options.json) {
+    process.stdout.write(
+      `${JSON.stringify({ state, iterations: fullIterations }, null, 2)}\n`
+    );
+    return 0;
+  }
+
+  process.stdout.write(
+    `${renderResultReport(state, fullIterations, {
+      iterationIndex,
+      withDiff: !!options.diff
+    })}\n`
+  );
+  return 0;
+}
+
+// ── model (show / set / clear / list) ─────────────────────────────
+//
+// Also manages reasoning effort — pass --effort <e> alongside a model name
+// to set both at once, or use --effort alone to change just the effort.
+async function handleModel(argv) {
+  const { options, positionals } = parseCommonArgs(argv);
+  const repoRoot = requireGitRepository(resolveCwd(options));
+
+  // --list is repo-independent — show supported aliases + valid efforts and exit.
+  if (options.list) {
+    const aliasLines = Object.entries(MODEL_ALIASES)
+      .map(([alias, full]) => `- \`${alias}\` \u2192 \`${full}\``)
+      .join("\n");
+    const effortLine = VALID_REASONING_EFFORTS.map((e) => `\`${e}\``).join(", ");
+    const body = [
+      "# CodexLoop model & reasoning aliases",
+      "",
+      `**Defaults:** model = \`${DEFAULT_MODEL}\`, reasoning effort = \`${DEFAULT_REASONING_EFFORT}\``,
+      "",
+      "## Model aliases",
+      "",
+      aliasLines || "- (none)",
+      "",
+      "Pass any model name to `cloop model <name>` (aliases are expanded before saving).",
+      "The actual set of usable models depends on your Codex subscription;",
+      "`cloop` does not hard-code a list beyond these aliases.",
+      "",
+      "## Valid reasoning efforts",
+      "",
+      effortLine
+    ].join("\n");
+    if (options.json) {
+      process.stdout.write(
+        `${JSON.stringify(
+          {
+            defaults: { model: DEFAULT_MODEL, reasoningEffort: DEFAULT_REASONING_EFFORT },
+            aliases: MODEL_ALIASES,
+            validReasoningEfforts: VALID_REASONING_EFFORTS
+          },
+          null,
+          2
+        )}\n`
+      );
+    } else {
+      process.stdout.write(`${body}\n`);
+    }
+    return 0;
+  }
+
+  const state = loadState(repoRoot);
+  if (!state.loopId) {
+    printError(
+      "No active loop. Run /cloop:start first (pass --model / --effort there), or use `cloop model --list` to see defaults."
+    );
+    return 1;
+  }
+
+  const hasNewModel = positionals.length > 0;
+  const hasNewEffort = options.effort !== undefined;
+  const isClear = !!options.clear;
+  const isShow = !hasNewModel && !hasNewEffort && !isClear;
+
+  // Parse inputs up-front so we fail before touching state if --effort is bogus.
+  let normalizedModel = null;
+  let normalizedEffort = null;
+  if (hasNewModel) {
+    if (positionals.length > 1) {
+      printError(
+        `cloop model: expected at most one model name, got ${positionals.length}: ${positionals.join(" ")}`
+      );
+      return 1;
+    }
+    normalizedModel = normalizeModelName(positionals[0]);
+    if (!normalizedModel) {
+      printError("cloop model: model name is empty.");
+      return 1;
+    }
+  }
+  if (hasNewEffort) {
+    try {
+      normalizedEffort = normalizeReasoningEffort(options.effort);
+    } catch (err) {
+      printError(err.message);
+      return 1;
+    }
+  }
+
+  // Show current config.
+  if (isShow) {
+    const body = [
+      "# CodexLoop model",
+      "",
+      "| field    | value |",
+      "|----------|-------|",
+      `| loopId   | \`${state.loopId}\` |`,
+      `| status   | ${state.status} |`,
+      `| model    | ${state.model ? `\`${state.model}\`` : "(codex default)"} |`,
+      `| effort   | ${state.reasoningEffort ? `\`${state.reasoningEffort}\`` : "(codex default)"} |`,
+      "",
+      `**Defaults** (used when state is cleared): model=\`${DEFAULT_MODEL}\`, effort=\`${DEFAULT_REASONING_EFFORT}\``,
+      "",
+      "Run `/cloop:model <name>` to change the model.",
+      "Run `/cloop:model --effort <level>` to change reasoning effort.",
+      "Run `/cloop:model <name> --effort <level>` to change both.",
+      "Run `/cloop:model --clear` to reset both to the codex CLI default.",
+      "Run `/cloop:model --list` to see known aliases and valid effort levels."
+    ].join("\n");
+
+    if (options.json) {
+      process.stdout.write(
+        `${JSON.stringify(
+          {
+            loopId: state.loopId,
+            status: state.status,
+            model: state.model,
+            reasoningEffort: state.reasoningEffort,
+            defaults: { model: DEFAULT_MODEL, reasoningEffort: DEFAULT_REASONING_EFFORT }
+          },
+          null,
+          2
+        )}\n`
+      );
+    } else {
+      process.stdout.write(`${body}\n`);
+    }
+    return 0;
+  }
+
+  if (["completed", "failed", "cancelled"].includes(state.status)) {
+    printError(
+      `Loop is in terminal state: ${state.status}. Start a new loop with /cloop:start --model <m> --effort <e>.`
+    );
+    return 1;
+  }
+
+  const s = loadState(repoRoot);
+  const previousModel = s.model ?? "(codex default)";
+  const previousEffort = s.reasoningEffort ?? "(codex default)";
+
+  if (isClear) {
+    s.model = null;
+    s.reasoningEffort = null;
+  } else {
+    if (hasNewModel) s.model = normalizedModel;
+    if (hasNewEffort) s.reasoningEffort = normalizedEffort;
+  }
+  saveState(repoRoot, s);
+
+  const aliasUsed =
+    hasNewModel &&
+    String(positionals[0]).trim().toLowerCase() !== normalizedModel &&
+    Object.prototype.hasOwnProperty.call(
+      MODEL_ALIASES,
+      String(positionals[0]).trim().toLowerCase()
+    );
+
+  if (options.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          loopId: s.loopId,
+          previous: { model: previousModel, reasoningEffort: previousEffort },
+          current: { model: s.model, reasoningEffort: s.reasoningEffort },
+          aliasExpanded: aliasUsed ? positionals[0] : null,
+          cleared: isClear
+        },
+        null,
+        2
+      )}\n`
+    );
+  } else {
+    const headerLine = isClear
+      ? "CodexLoop model + effort cleared."
+      : "CodexLoop model/effort updated.";
+    const lines = [
+      headerLine,
+      `  previous model:  ${previousModel}`,
+      `  current  model:  ${s.model ?? "(codex default)"}`,
+      `  previous effort: ${previousEffort}`,
+      `  current  effort: ${s.reasoningEffort ?? "(codex default)"}`,
+      `  loopId:          ${s.loopId}`
+    ];
+    if (aliasUsed) {
+      lines.push(`  (expanded alias '${positionals[0]}' -> '${normalizedModel}')`);
+    }
+    lines.push("", "The next iteration will use these settings.");
+    process.stdout.write(lines.join("\n") + "\n");
+  }
+  return 0;
+}
+
+// ── loop-worker (internal) ─────────────────────────────────────────
+async function handleWorker(argv) {
+  const { options } = parseCommonArgs(argv);
+  const repoRoot = resolveCwd(options);
+  const loopId = options["loop-id"] ?? null;
+
+  try {
+    acquireLock(repoRoot, { pid: process.pid, loopId });
+  } catch (err) {
+    const s = loadState(repoRoot);
+    s.status = "failed";
+    s.error = {
+      kind: err instanceof LoopLockError ? "lock" : err.name ?? "Error",
+      message: err.message ?? String(err)
+    };
+    s.completedAt = nowIso();
+    saveState(repoRoot, s);
+    printError(`Worker failed to acquire lock: ${err.message}`);
+    return 2;
+  }
+  writePidFile(repoRoot, process.pid);
+
+  try {
+    const s = loadState(repoRoot);
+    s.status = "running";
+    s.pid = process.pid;
+    saveState(repoRoot, s);
+
+    await runLoop({ repoRoot, runOpts: {} });
+  } catch (err) {
+    const sf = loadState(repoRoot);
+    sf.status = "failed";
+    sf.error = { kind: err.kind ?? err.name ?? "Error", message: err.message };
+    sf.completedAt = nowIso();
+    saveState(repoRoot, sf);
+    printError(`Worker failed: ${err.message}`);
+  } finally {
+    removePidFile(repoRoot);
+    releaseLock(repoRoot);
+  }
+  return 0;
+}