quest-loop 0.1.0 → 0.3.0

package/lib/codex-native.mjs

@@ -0,0 +1,246 @@
+// Codex-native setup helpers. These are intentionally kept out of the quest
+// store layer: they inspect/install Codex integration files, not quest records.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const PLUGIN_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const AGENTS = ["quest-executor", "quest-reviewer"];
+
+function readJson(rel) {
+  return JSON.parse(readFileSync(join(PLUGIN_ROOT, rel), "utf8"));
+}
+
+// Like readJson but returns null instead of throwing. The plugin manifests
+// (.codex-plugin / .claude-plugin) are NOT part of the npm `files` allow-list,
+// so they are absent from a pure `npm install -g quest-loop` install — reading
+// them must never crash `quest --version` or `quest codex doctor`.
+function readJsonSafe(rel) {
+  try {
+    return readJson(rel);
+  } catch {
+    return null;
+  }
+}
+
+function runCmd(cmd, args, { cwd, env } = {}) {
+  return spawnSync(cmd, args, {
+    cwd,
+    env,
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+  });
+}
+
+function check(name, ok, detail, extra = {}) {
+  return { name, ok: Boolean(ok), detail, ...extra };
+}
+
+function projectRoot(cwd, env) {
+  const res = runCmd("git", ["rev-parse", "--show-toplevel"], { cwd, env });
+  if (res.status === 0 && res.stdout.trim()) return res.stdout.trim();
+  return resolve(cwd);
+}
+
+function targetDir(scope, cwd, env) {
+  if (scope === "user") return join(homedir(), ".codex", "agents");
+  if (scope === "project") return join(projectRoot(cwd, env), ".codex", "agents");
+  throw new Error(`--scope must be project or user (got "${scope}")`);
+}
+
+function installedAgentDirs(cwd, env) {
+  return [
+    join(projectRoot(cwd, env), ".codex", "agents"),
+    join(homedir(), ".codex", "agents"),
+  ];
+}
+
+function sameFile(path, text) {
+  try {
+    return readFileSync(path, "utf8") === text;
+  } catch {
+    return false;
+  }
+}
+
+function extractTexts(promptInputJson) {
+  try {
+    const items = JSON.parse(promptInputJson);
+    const texts = [];
+    const walk = (v) => {
+      if (Array.isArray(v)) return v.forEach(walk);
+      if (!v || typeof v !== "object") return;
+      if (typeof v.text === "string") texts.push(v.text);
+      if (typeof v.content === "string") texts.push(v.content);
+      for (const child of Object.values(v)) walk(child);
+    };
+    walk(items);
+    return texts.join("\n");
+  } catch {
+    return promptInputJson;
+  }
+}
+
+function questSkillEntries(promptInputJson) {
+  const text = extractTexts(promptInputJson);
+  const entries = new Map();
+  const re = /- quest:(plan|work|orchestrate|retro|protocol|setup):[^\n]+\(file: ([^)]+)\)/g;
+  for (const m of text.matchAll(re)) entries.set(m[1], m[2]);
+  return [...entries.entries()].map(([name, path]) => ({ name, path })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function pathRootForQuestSkill(path) {
+  // Match POSIX `/skills/` and Windows `\skills\` so the neutral-root check
+  // does not falsely split every skill path into its own root on Windows.
+  const i = path.search(/[/\\]skills[/\\]/);
+  return i === -1 ? path : path.slice(0, i);
+}
+
+export function versionInfo() {
+  // package.json is always shipped; the plugin manifests may be absent on a
+  // CLI-only npm install, so they are read tolerantly.
+  const pkg = readJson("package.json");
+  const codexManifest = readJsonSafe(".codex-plugin/plugin.json");
+  const claudeManifest = readJsonSafe(".claude-plugin/plugin.json");
+  return {
+    package: pkg.version,
+    codex: codexManifest?.version ?? null,
+    claude: claudeManifest?.version ?? null,
+  };
+}
+
+export function installAgents({ scope = "project", dryRun = false, force = false, cwd = process.cwd(), env = process.env } = {}) {
+  const dir = targetDir(scope, cwd, env);
+
+  // Plan every agent first; only touch disk once the whole set is known to be
+  // conflict-free. A mixed create+conflict run must not leave a partial install.
+  const plans = AGENTS.map((name) => {
+    const src = join(PLUGIN_ROOT, "agents", `${name}.toml`);
+    const dest = join(dir, `${name}.toml`);
+    const text = readFileSync(src, "utf8");
+    const exists = existsSync(dest);
+    let action;
+    if (exists && sameFile(dest, text)) action = "unchanged";
+    else if (exists && !force) action = "conflict";
+    else action = exists ? "replace" : "create";
+    return { name, path: dest, action, text };
+  });
+
+  const conflicts = plans.filter((p) => p.action === "conflict").map(({ name, path }) => ({ name, path }));
+  const actions = plans.map(({ name, path, action }) => ({ name, path, action }));
+  const ok = conflicts.length === 0;
+
+  if (ok && !dryRun) {
+    for (const p of plans) {
+      if (p.action === "unchanged") continue;
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(p.path, p.text);
+    }
+  }
+
+  return { ok, scope, target: dir, dry_run: dryRun, actions, conflicts };
+}
+
+export function doctor({ cwd = process.cwd(), env = process.env } = {}) {
+  const checks = [];
+  const versions = versionInfo();
+  // package.json ships everywhere; the plugin manifests may be absent on a
+  // CLI-only npm install. Treat absent manifests as "not applicable" rather than
+  // a hard mismatch, and fall back to the package version as the expected plugin
+  // version so a legitimate CLI-only doctor run is not spuriously red.
+  const manifestVersion = versions.codex ?? versions.package;
+  const presentManifests = [["codex", versions.codex], ["claude", versions.claude]].filter(([, v]) => v != null);
+  const absent = ["codex", "claude"].filter((k) => versions[k] == null);
+
+  checks.push(check(
+    "version-sync",
+    presentManifests.every(([, v]) => v === versions.package),
+    `package=${versions.package}, codex=${versions.codex ?? "absent"}, claude=${versions.claude ?? "absent"}` +
+      (absent.length ? ` (${absent.join(", ")} manifest absent — CLI-only install)` : ""),
+    { versions },
+  ));
+
+  const codexVersion = runCmd("codex", ["--version"], { cwd, env });
+  checks.push(check(
+    "codex-cli",
+    codexVersion.status === 0,
+    codexVersion.status === 0 ? codexVersion.stdout.trim() : (codexVersion.stderr || codexVersion.error?.message || "codex not found").trim(),
+  ));
+
+  if (codexVersion.status === 0) {
+    const list = runCmd("codex", ["plugin", "list", "--json"], { cwd, env });
+    let installed;
+    try {
+      const parsed = JSON.parse(list.stdout || "{}");
+      installed = (parsed.installed || []).find((p) => p.pluginId === "quest@quest" || (p.name === "quest" && p.marketplaceName === "quest"));
+    } catch {
+      installed = null;
+    }
+    checks.push(check(
+      "plugin-installed",
+      list.status === 0 && installed?.enabled === true,
+      installed ? `quest@quest ${installed.version} enabled=${installed.enabled}` : (list.stderr || "quest@quest not installed").trim(),
+      { installed: installed ?? null },
+    ));
+    checks.push(check(
+      "plugin-version",
+      Boolean(installed && installed.version === manifestVersion),
+      installed ? `installed=${installed.version}, manifest=${manifestVersion}` : `manifest=${manifestVersion}`,
+    ));
+
+    const debug = runCmd("codex", ["debug", "prompt-input", "noop"], { cwd: tmpdir(), env });
+    // Require a hook-parse *problem*, not merely the word "hook" next to "warnings".
+    // Matches both orderings ("hook parse warning" / "failed to parse hook") while
+    // ignoring benign summaries like "loaded 4 hooks, 0 warnings".
+    const hookWarning = /(?:parse|parsing)[^\n]*\bhook\b|\bhook\b[^\n]*(?:parse|parsing|invalid|malformed)|failed to (?:parse|load)[^\n]*\bhook\b/i.test(debug.stderr || "");
+    checks.push(check(
+      "hook-parser",
+      debug.status === 0 && !hookWarning,
+      debug.status === 0 ? (hookWarning ? debug.stderr.trim() : "no hook parse warnings") : (debug.stderr || "codex debug failed").trim(),
+    ));
+
+    const entries = debug.status === 0 ? questSkillEntries(debug.stdout) : [];
+    const requiredSkills = ["plan", "work", "orchestrate", "retro", "protocol"];
+    const missingSkills = requiredSkills.filter((name) => !entries.some((entry) => entry.name === name));
+    const paths = entries.map((entry) => entry.path);
+    const roots = [...new Set(paths.map(pathRootForQuestSkill))];
+    checks.push(check(
+      "single-neutral-skill-root",
+      missingSkills.length === 0 && roots.length === 1,
+      paths.length ? `${entries.length} quest skills across ${roots.length} root(s)` : "quest skills not found in neutral prompt-input",
+      { skills: entries, missing_skills: missingSkills, skill_paths: paths, skill_roots: roots },
+    ));
+  }
+
+  const agentDirs = installedAgentDirs(cwd, env);
+  const missing = [];
+  const stale = [];
+  const found = {};
+  for (const name of AGENTS) {
+    const bundled = readFileSync(join(PLUGIN_ROOT, "agents", `${name}.toml`), "utf8");
+    const path = agentDirs.map((dir) => join(dir, `${name}.toml`)).find((p) => existsSync(p));
+    if (!path) {
+      missing.push(name);
+      continue;
+    }
+    found[name] = path;
+    // Existence alone can mask a stale user-scope copy shadowing an out-of-date
+    // project install — compare against the bundled definition.
+    if (!sameFile(path, bundled)) stale.push(name);
+  }
+  const agentDetail = [
+    missing.length ? `missing: ${missing.join(", ")}` : null,
+    stale.length ? `stale (run install-agents --force): ${stale.join(", ")}` : null,
+  ].filter(Boolean).join("; ") || `found: ${Object.values(found).join(", ")}`;
+  checks.push(check(
+    "native-agents",
+    missing.length === 0 && stale.length === 0,
+    agentDetail,
+    { found, missing, stale },
+  ));
+
+  return { ok: checks.every((c) => c.ok), checks };
+}

package/lib/config.mjs

@@ -16,7 +16,7 @@ export class ConfigError extends Error {
 export const BUILTIN_DEFAULTS = {
   worker: "claude",
   claude: { model: "opus", effort: "xhigh" },
-  codex: { model: "gpt-5.5", reasoning_effort: "medium" },
+  codex: { model: "gpt-5.5", reasoning_effort: "medium", goal_mode: "auto" },
   max_iterations: 8,
   priority: "p2",
 };

package/lib/contract.mjs

@@ -79,7 +79,7 @@ export function parseCheckpoints(body) {
   return checkpoints;
 }
 
-export function makeCheckpoint({ timestamp, quest_status, iteration, changed, validation_summary, pr, head_sha, failed_approaches, compatible_expansion, note }) {
+export function makeCheckpoint({ timestamp, quest_status, iteration, changed, validation_summary, pr, head_sha, failed_approaches, compatible_expansion, reopen_reason, note }) {
   if (!QUEST_STATUSES.includes(quest_status)) {
     throw new ContractError(`quest_status must be one of ${QUEST_STATUSES.join(" | ")} (got "${quest_status}")`, { hint: "store statuses like todo/cancelled are not checkpoint verdicts" });
   }
@@ -100,6 +100,7 @@ export function makeCheckpoint({ timestamp, quest_status, iteration, changed, va
   out.push(`- validation_summary: ${oneLine("validation_summary", validation_summary)}`);
   if (failed_approaches) out.push(`- failed_approaches: ${oneLine("failed_approaches", failed_approaches)}`);
   if (compatible_expansion) out.push(`- compatible_expansion: ${oneLine("compatible_expansion", compatible_expansion)}`);
+  if (reopen_reason) out.push(`- reopen_reason: ${oneLine("reopen_reason", reopen_reason)}`);
   if (note && String(note).trim() !== "") out.push("", String(note).trim());
   return out.join("\n");
 }
@@ -122,11 +123,30 @@ const TRANSITIONS = {
 export function assertTransition(from, to) {
   if (!(TRANSITIONS[from] ?? []).includes(to)) {
     throw new ContractError(`illegal status transition: ${from} → ${to}`, {
-      hint: from === "complete" || from === "cancelled" ? `${from} is terminal — file a new quest instead` : `legal from "${from}": ${TRANSITIONS[from].join(", ") || "(none)"}`,
+      hint:
+        from === "complete"
+          ? "complete is terminal for checkpoints — use `quest reopen <id> --reason` to legally re-enter the loop"
+          : from === "cancelled"
+          ? "cancelled is terminal — file a new quest instead"
+          : `legal from "${from}": ${(TRANSITIONS[from] ?? []).join(", ") || "(none)"}`,
     });
   }
 }
 
+// The single legal path from a terminal `complete` status back into the loop.
+// Deliberately NOT part of TRANSITIONS.complete (which stays []): only the
+// `quest reopen` verb calls this, so a stray checkpoint can never resurrect a
+// complete quest. `cancelled` stays fully terminal — file a new quest instead.
+export function assertReopen(from) {
+  if (from === "complete") return;
+  throw new ContractError(`cannot reopen a ${from} quest — only complete quests are reopenable`, {
+    hint:
+      from === "cancelled"
+        ? "cancelled is terminal — file a new quest instead"
+        : `${from} is not terminal; advance it with \`quest checkpoint\` (or \`quest start\` if todo)`,
+  });
+}
+
 export function lintRecord({ front, body, checkpoints }, { filename } = {}) {
   const problems = [];
   for (const key of REQUIRED_FRONT) {

package/lib/help.mjs

@@ -51,7 +51,7 @@ export const COMMANDS = {
     flags: [
       ["--status <s>", "todo | in_progress | blocked | complete | cancelled"],
       ["--parent <id>", "children of an epic"],
-      ["--ready", "todo quests whose depends_on are all complete (dispatch order)"],
+      ["--ready", "todo quests whose depends_on are all complete, excluding epics with open children (dispatch order)"],
       ["--json", "machine-readable output"],
     ],
     example: "quest list --ready",
@@ -92,6 +92,12 @@ export const COMMANDS = {
     flags: [["--reason <why>", "required — recorded in the record"]],
     example: 'quest cancel 4 --reason "superseded by quest 7"',
   },
+  reopen: {
+    purpose: "Reopen a complete quest back into the loop (complete → in_progress)",
+    usage: "quest reopen <id> --reason <why>",
+    flags: [["--reason <why>", "required — recorded in an audited reopen checkpoint"]],
+    example: 'quest reopen 4 --reason "review found npm audit criticals after completion"',
+  },
   edit: {
     purpose: "Compatibly expand a quest (additions only; anchors are immutable)",
     usage: "quest edit <id> [--add-done-when D]… [--add-milestone M]… [--add-context C] --rationale <why>",
@@ -130,6 +136,19 @@ export const COMMANDS = {
     ],
     example: "quest runs --active",
   },
+  codex: {
+    purpose: "Inspect or install Quest's native Codex integration",
+    usage: "quest codex doctor [--json] | quest codex install-agents [--scope project|user] [--dry-run] [--force] [--json]",
+    flags: [
+      ["doctor", "check Codex CLI, plugin install/version, hooks, skill roots, and native agents"],
+      ["install-agents", "install quest-executor and quest-reviewer as native Codex custom agents"],
+      ["--scope <s>", "project (default: .codex/agents at repo root) or user (~/.codex/agents)"],
+      ["--dry-run", "show intended agent writes without changing files"],
+      ["--force", "replace existing agent files"],
+      ["--json", "machine-readable output"],
+    ],
+    example: "quest codex install-agents --scope project && quest codex doctor",
+  },
 };
 
 export function renderCommandHelp(name) {
@@ -163,7 +182,7 @@ export function renderStatusOverview({ counts, ready, activeRuns, backend }) {
     for (const q of ready.slice(0, 3)) lines.push(`  ${q.id}. [${q.priority}] ${q.title}`);
     lines.push("", "Next: `quest show <id>` to read one, or dispatch with `quest-run <id>`.");
   } else if (!parts.length) {
-    lines.push("", "Next: create your first quest — see `quest create --help` (or use the /quest:plan skill).");
+    lines.push("", "Next: create your first quest — see `quest create --help` (or use the $quest:plan skill).");
   } else {
     lines.push("", "Nothing ready to start. `quest list` to see everything.");
   }
@@ -187,9 +206,9 @@ export function renderInitNextSteps(backend) {
   return [
     "",
     "Store created. Next steps:",
-    "  1. Author a quest:   quest create --help   (or /quest:plan in your agent session)",
+    "  1. Author a quest:   quest create --help   (or $quest:plan in your agent session)",
     "  2. Check it:         quest lint --all",
-    "  3. Work it:          /quest:work <id> in-session, or quest-run <id> headless",
+    "  3. Work it:          $quest:work <id> in-session, or quest-run <id> headless",
     ...(backend === "github" ? ["", "Records live as GitHub issues; config and amendments stay local in .quests/."] : []),
   ].join("\n");
 }

package/lib/runner.mjs

@@ -34,10 +34,11 @@ class RunUsageError extends Error {
 // ---------------------------------------------------------------------------
 
 const HELP = {
-  purpose: "Drive a headless Claude or Codex worker through a quest in native goal mode.",
+  purpose: "Drive a headless Claude or Codex worker through a quest with checkpoint-based stop checks.",
   usage: [
     "quest-run <id> [--worker claude|codex] [--model M] [--effort E]",
     "              [--max-iterations N] [--max-cost USD] [--codex-sandbox MODE]",
+    "              [--codex-goal-mode auto|require|off]",
     "              [--continue-session] [--notify '<cmd>'] [--dry-run] [--json]",
     "quest-run --ready [--parallel N] [--isolate worktree] [--dry-run] [--json]",
   ],
@@ -51,6 +52,7 @@ const HELP = {
     ["--max-tokens <n>", "token cap; governs codex spend since USD is unreported → blocked, exit 11"],
     ["--session-timeout <s>", "per-session wall-clock cap (seconds); a hung worker is killed and the session counts as a stall (default 1800; config defaults.session_timeout)"],
     ["--codex-sandbox <mode>", "codex exec sandbox: read-only | workspace-write | danger-full-access (default workspace-write; config defaults.codex.sandbox). workspace-write BLOCKS git commits — commit quests need danger-full-access"],
+    ["--codex-goal-mode <mode>", "codex goal-tool policy: auto | require | off (default auto; config defaults.codex.goal_mode)"],
     ["--continue-session", "resume the previous session each iteration instead of a fresh one"],
     ["--notify <cmd>", "shell command run on run end (env: QUEST_ID, QUEST_TITLE, FINAL_STATUS, ITERATIONS, COST)"],
     ["--dry-run", "print the exact worker invocation and exit without spawning"],
@@ -68,6 +70,8 @@ const HELP = {
     "codex's default --codex-sandbox workspace-write write-protects .git, so a codex worker",
     "cannot `git commit` under it; a commit-requiring quest must opt into danger-full-access —",
     "an explicit tradeoff (full disk + network access), never escalated silently.",
+    "codex goal tools are optional by default; --codex-goal-mode require blocks honestly if",
+    "the exec surface does not expose or invoke them.",
     "Without --isolate, parallel quests are assumed file-disjoint (no locking beyond the store's).",
     "--isolate worktree leaves the worktree + quest/<id>-<slug> branch in place; the PR is the merge path.",
   ],
@@ -203,7 +207,11 @@ function resolveOptions(front, config, flags) {
   if ((flags["codex-sandbox"] != null || worker === "codex") && !CODEX_SANDBOX_MODES.includes(codexSandbox)) {
     throw new RunUsageError(`--codex-sandbox must be one of ${CODEX_SANDBOX_MODES.join(", ")} (got "${codexSandbox}")`);
   }
-  return { worker, model, effort, maxIterations, maxCost, maxTokens, sessionTimeout, codexSandbox };
+  const codexGoalMode = flags["codex-goal-mode"] ?? config.defaults.codex?.goal_mode ?? "auto";
+  if ((flags["codex-goal-mode"] != null || worker === "codex") && !["auto", "require", "off"].includes(codexGoalMode)) {
+    throw new RunUsageError(`--codex-goal-mode must be one of auto, require, off (got "${codexGoalMode}")`);
+  }
+  return { worker, model, effort, maxIterations, maxCost, maxTokens, sessionTimeout, codexSandbox, codexGoalMode };
 }
 
 function lastSessionIdFor(storeDir, questId, worker) {
@@ -273,6 +281,7 @@ async function runQuest(storeDir, config, id, flags, io, { cwd } = {}) {
       schemaPath: SCHEMA_PATH,
       runStartIso,
       codexSandbox: opts.codexSandbox,
+      codexGoalMode: opts.codexGoalMode,
     };
     const inv = adapter.buildInvocation(initial, config, invOpts);
     if (flags.json) {
@@ -301,6 +310,7 @@ async function runQuest(storeDir, config, id, flags, io, { cwd } = {}) {
     if (initial.status === "complete") {
       finalStatus = "complete";
       exitCode = 0;
+      io.errOut(`quest-run: quest ${id} is already complete — nothing to run. To legally re-enter the loop, run \`quest reopen ${id} --reason "<why>"\` first (never hand-edit the status line).`);
     } else if (initial.status === "cancelled") {
       finalStatus = "cancelled";
       exitCode = 0;
@@ -394,6 +404,7 @@ async function runQuest(storeDir, config, id, flags, io, { cwd } = {}) {
             schemaPath: SCHEMA_PATH,
             runStartIso,
             codexSandbox: opts.codexSandbox,
+            codexGoalMode: opts.codexGoalMode,
           },
           runStartIso,
           iteration: sessionsRun,
@@ -428,6 +439,8 @@ async function runQuest(storeDir, config, id, flags, io, { cwd } = {}) {
         // landed before the kill — a terminal status is still caught at the top
         // of the next iteration, so completions are never lost.
         const progressed = newCheckpoint && !sessionTimedOut;
+        // Journal the session BEFORE any terminal break so `quest runs` telemetry
+        // (iteration count, cost, tokens) is never dropped for the final session.
         local.appendRunEvent(storeDir, {
           event: "iteration_finished",
           run_id: runId,
@@ -441,6 +454,25 @@ async function runQuest(storeDir, config, id, flags, io, { cwd } = {}) {
           status_after: after ? after.status : null,
         });
 
+        // Goal-mode `require`: block whenever create_goal was required but never
+        // observed and the quest is still OPEN — a milestone checkpoint does not
+        // satisfy the requirement. A genuinely complete/blocked/cancelled quest is
+        // respected (its evidence trail stands on its own). A LOST record (`!after`)
+        // is not "open": let the missing-record path at the loop top surface it.
+        const questOpen = after && (after.status === "in_progress" || after.status === "todo");
+        if (opts.worker === "codex" && result.goalToolMissingRequired && questOpen) {
+          await recordBlocked(
+            storeDir,
+            env,
+            id,
+            "runner: codex goal tools were required but no create_goal tool call was observed",
+            "runner codex goal-mode enforcement",
+          );
+          finalStatus = "blocked";
+          exitCode = 10;
+          break;
+        }
+
         if (progressed) {
           stall = 0;
           if (after.status === "complete") {
@@ -538,6 +570,7 @@ async function runReady(storeDir, config, flags, io) {
 
   const summaries = [];
   const done = new Set();
+  const skippedEpics = new Set();
   const inFlight = new Map();
 
   const readyIds = async () => {
@@ -550,6 +583,22 @@ async function runReady(storeDir, config, flags, io) {
     }
   };
 
+  // Ids that at least one quest names as its parent — i.e. epics. Epics are
+  // closed by the orchestrator inline (verify children, run the epic validation
+  // loop, checkpoint), never dispatched to a worker. readyQuests already gates
+  // out epics with open children; this catches the fully-verified epic that has
+  // become "ready" so --ready still refuses to burn a worker run on it. A
+  // direct `quest-run <id>` on an epic stays allowed.
+  const epicIds = async () => {
+    const { stdout, code } = await questCli(storeDir, io.env, ["list", "--json"]);
+    if (code !== 0) return new Set();
+    try {
+      return new Set(JSON.parse(stdout).filter((q) => q.parent !== undefined).map((q) => q.parent));
+    } catch {
+      return new Set();
+    }
+  };
+
   const startOne = (id) => {
     const promise = (async () => {
       let cwd = io.cwd;
@@ -570,8 +619,14 @@ async function runReady(storeDir, config, flags, io) {
   };
 
   for (;;) {
-    const ready = (await readyIds()).filter((id) => !done.has(id) && !inFlight.has(id));
+    const epics = await epicIds();
+    const ready = (await readyIds()).filter((id) => !done.has(id) && !inFlight.has(id) && !skippedEpics.has(id));
     for (const id of ready) {
+      if (epics.has(id)) {
+        skippedEpics.add(id);
+        io.errOut(`quest-run: quest ${id} is an epic (other quests name it as parent) — refusing to auto-dispatch it. Close it inline per $quest:orchestrate: verify its children, run the epic validation loop, then \`quest checkpoint ${id} --status complete\`. Never burn a worker run on an epic.`);
+        continue;
+      }
       if (inFlight.size >= parallel) break;
       startOne(id);
     }
@@ -626,6 +681,7 @@ export async function run(argv, io = {}) {
         "max-tokens": { type: "string" },
         "session-timeout": { type: "string" },
         "codex-sandbox": { type: "string" },
+        "codex-goal-mode": { type: "string" },
         "continue-session": { type: "boolean" },
         notify: { type: "string" },
         "dry-run": { type: "boolean" },

package/lib/store-github.mjs

@@ -20,6 +20,7 @@ import {
   ContractError,
   appendToSection,
   appendUnderCheckpoints,
+  assertReopen,
   assertTransition,
   lintRecord,
   makeCheckpoint,
@@ -267,12 +268,19 @@ export function listQuests(repo, env) {
   });
 }
 
-// Same readiness rule as store-local.readyQuests, over the remote list.
+// Same readiness rule as store-local.readyQuests, over the remote list —
+// including the epic gate: a quest with any non-terminal child (a quest whose
+// parent points at it, not in complete/cancelled) is never ready. Epics are
+// closed by the orchestrator inline, never auto-dispatched; a cancelled child
+// is terminal so it cannot wedge the epic forever.
 export function readyQuests(repo, env) {
   const all = listQuests(repo, env);
   const done = new Set(all.filter((q) => q.status === "complete").map((q) => q.id));
+  const openParents = new Set(
+    all.filter((q) => q.parent !== undefined && q.status !== "complete" && q.status !== "cancelled").map((q) => q.parent),
+  );
   return all
-    .filter((q) => q.status === "todo" && (q.depends_on ?? []).every((d) => done.has(d)))
+    .filter((q) => q.status === "todo" && !openParents.has(q.id) && (q.depends_on ?? []).every((d) => done.has(d)))
     .sort((a, b) => a.priority.localeCompare(b.priority) || a.id - b.id);
 }
 
@@ -372,10 +380,34 @@ export function cancelQuest(repo, id, reason, env) {
   return { front: { ...rec.front, status: "cancelled", updated } };
 }
 
+// Comment-first, mirroring cancelQuest's operation order: post the audited
+// reopen checkpoint, refresh the meta timestamp, then swap the label
+// (quest:complete → quest:in-progress) and reopen the issue via applyStatus.
+export function reopenQuest(repo, id, reason, env) {
+  if (!reason || !reason.trim()) throw new ContractError("reopen requires --reason", { hint: 'example: quest reopen 4 --reason "review found npm audit criticals"' });
+  const rec = reconstruct(viewIssue(repo, id, env));
+  assertReopen(rec.front.status);
+  const block = makeCheckpoint({
+    timestamp: nowIso(),
+    quest_status: "in_progress",
+    iteration: rec.checkpoints.length + 1,
+    changed: "reopened from complete",
+    validation_summary: "reopened for further work; no execution this entry",
+    reopen_reason: reason.trim(),
+  });
+  gh(["issue", "comment", String(id), "--repo", repo, "--body-file", "-"], { env, input: block });
+  const updated = nowIso();
+  writeStoredBody(repo, id, { ...rec.meta, updated }, rec.storedSections, env);
+  applyStatus(repo, id, rec.labels, rec.state, "in_progress", env);
+  return { front: { ...rec.front, status: "in_progress", updated }, checkpoints: [...rec.checkpoints, ...parseCheckpoints(block)] };
+}
+
 export function editQuest(repo, id, { addDoneWhen = [], addMilestone = [], addContext, rationale }, env) {
   if (!rationale || !rationale.trim()) throw new ContractError("edit requires --rationale (scope changes are recorded, per protocol)", { hint: "state why this is a compatible expansion of the Objective" });
   if (!addDoneWhen.length && !addMilestone.length && !addContext) throw new ContractError("nothing to add — pass --add-done-when, --add-milestone, or --add-context", { hint: "the Objective and existing Done-when items are immutable by design" });
   const rec = reconstruct(viewIssue(repo, id, env));
+  if (rec.front.status === "complete") throw new ContractError("cannot edit a complete quest", { hint: "reopen it first with `quest reopen <id> --reason`, then edit — or file a new quest" });
+  if (rec.front.status === "cancelled") throw new ContractError("cannot edit a cancelled quest", { hint: "cancelled is terminal — file a new quest instead" });
   let sections = rec.storedSections;
   for (const item of addDoneWhen) sections = appendToSection(sections, "## Done when", `- [ ] ${item}`);
   for (const item of addMilestone) sections = appendToSection(sections, "## Milestones", `- [ ] ${item}`, { createAfter: "## Validation loop" });

package/lib/store-local.mjs

@@ -4,7 +4,7 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, writeFileSync, statSync, appendFileSync } from "node:fs";
 import { join, basename } from "node:path";
-import { ContractError, appendToSection, appendUnderCheckpoints, assertTransition, lintRecord, makeCheckpoint, nowIso, parseRecord, recordFilename, renderBody, serializeRecord, CHECKPOINT_MARKER } from "./contract.mjs";
+import { ContractError, appendToSection, appendUnderCheckpoints, assertReopen, assertTransition, lintRecord, makeCheckpoint, nowIso, parseRecord, recordFilename, renderBody, serializeRecord, CHECKPOINT_MARKER } from "./contract.mjs";
 
 export class NotFoundError extends Error {
   constructor(id) {
@@ -85,8 +85,15 @@ export function listQuests(storeDir) {
 export function readyQuests(storeDir) {
   const all = listQuests(storeDir);
   const done = new Set(all.filter((q) => q.status === "complete").map((q) => q.id));
+  // Epic gate: a quest with any non-terminal child (a quest whose parent points
+  // at it, not in complete/cancelled) is never ready. Epics are closed by the
+  // orchestrator inline (see $quest:orchestrate), never auto-dispatched. A
+  // cancelled child is terminal so it cannot wedge the epic forever.
+  const openParents = new Set(
+    all.filter((q) => q.parent !== undefined && q.status !== "complete" && q.status !== "cancelled").map((q) => q.parent),
+  );
   return all
-    .filter((q) => q.status === "todo" && (q.depends_on ?? []).every((d) => done.has(d)))
+    .filter((q) => q.status === "todo" && !openParents.has(q.id) && (q.depends_on ?? []).every((d) => done.has(d)))
     .sort((a, b) => a.priority.localeCompare(b.priority) || a.id - b.id);
 }
 
@@ -162,10 +169,33 @@ export function cancelQuest(storeDir, id, reason) {
   });
 }
 
+// The audited path from complete back into the loop (mirrors cancelQuest, but
+// flips complete → in_progress and appends a real checkpoint carrying the
+// reopen_reason). Uses assertReopen, never assertTransition — a checkpoint can
+// never resurrect a complete quest; only this verb can.
+export function reopenQuest(storeDir, id, reason) {
+  if (!reason || !reason.trim()) throw new ContractError("reopen requires --reason", { hint: 'example: quest reopen 4 --reason "review found npm audit criticals"' });
+  return updateQuest(storeDir, id, (q) => {
+    assertReopen(q.front.status);
+    const block = makeCheckpoint({
+      timestamp: nowIso(),
+      quest_status: "in_progress",
+      iteration: q.checkpoints.length + 1,
+      changed: "reopened from complete",
+      validation_summary: "reopened for further work; no execution this entry",
+      reopen_reason: reason.trim(),
+    });
+    const body = appendUnderCheckpoints(q.body, block);
+    return { front: { ...q.front, status: "in_progress" }, body };
+  });
+}
+
 export function editQuest(storeDir, id, { addDoneWhen = [], addMilestone = [], addContext, rationale }) {
   if (!rationale || !rationale.trim()) throw new ContractError("edit requires --rationale (scope changes are recorded, per protocol)", { hint: "state why this is a compatible expansion of the Objective" });
   if (!addDoneWhen.length && !addMilestone.length && !addContext) throw new ContractError("nothing to add — pass --add-done-when, --add-milestone, or --add-context", { hint: "the Objective and existing Done-when items are immutable by design" });
   return updateQuest(storeDir, id, (q) => {
+    if (q.front.status === "complete") throw new ContractError("cannot edit a complete quest", { hint: "reopen it first with `quest reopen <id> --reason`, then edit — or file a new quest" });
+    if (q.front.status === "cancelled") throw new ContractError("cannot edit a cancelled quest", { hint: "cancelled is terminal — file a new quest instead" });
     let body = q.body;
     for (const item of addDoneWhen) body = appendToSection(body, "## Done when", `- [ ] ${item}`);
     for (const item of addMilestone) body = appendToSection(body, "## Milestones", `- [ ] ${item}`, { createAfter: "## Validation loop" });

package/lib/store.mjs

@@ -18,6 +18,7 @@ export function openStore(config, ctx = {}) {
       startQuest: (id) => github.startQuest(repo, id, env),
       appendCheckpoint: (id, cp) => github.appendCheckpoint(repo, id, cp, env),
       cancelQuest: (id, reason) => github.cancelQuest(repo, id, reason, env),
+      reopenQuest: (id, reason) => github.reopenQuest(repo, id, reason, env),
       editQuest: (id, changes) => github.editQuest(repo, id, changes, env),
       lintAll: () => github.lintAll(repo, env),
     };
@@ -31,6 +32,7 @@ export function openStore(config, ctx = {}) {
     startQuest: (id) => local.startQuest(dir, id),
     appendCheckpoint: (id, cp) => local.appendCheckpoint(dir, id, cp),
     cancelQuest: (id, reason) => local.cancelQuest(dir, id, reason),
+    reopenQuest: (id, reason) => local.reopenQuest(dir, id, reason),
     editQuest: (id, changes) => local.editQuest(dir, id, changes),
     lintAll: () => local.lintAll(dir),
   };