quest-loop 0.3.4 → 0.3.6

package/lib/codex-native.mjs

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 
 const PLUGIN_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const AGENTS = ["quest-executor", "quest-reviewer"];
+const QUEST_CODEX_MARKETPLACE_SOURCE = ["roberts", "reberski/quest"].join("");
 const PROVIDERS = {
   codex: {
     label: "Codex",
@@ -160,7 +161,19 @@ export function versionInfo() {
   };
 }
 
-function installProviderAgents(provider, { scope = "project", dryRun = false, force = false, cwd = process.cwd(), env = process.env } = {}) {
+function existingAgentMatchesName(provider, name, path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return false;
+  }
+  if (provider === "codex") return new RegExp(`^\\s*name\\s*=\\s*"${name}"\\s*$`, "m").test(text);
+  if (provider === "claude") return new RegExp(`^\\s*name:\\s*${name}\\s*$`, "m").test(text);
+  return false;
+}
+
+function installProviderAgents(provider, { scope = "project", dryRun = false, force = false, replaceStale = true, cwd = process.cwd(), env = process.env } = {}) {
   const cfg = providerConfig(provider);
   const dir = targetDir(provider, scope, cwd, env);
   const dirConflicts = [dirname(dir), dir]
@@ -175,9 +188,10 @@ function installProviderAgents(provider, { scope = "project", dryRun = false, fo
     const dest = join(dir, `${name}.${cfg.extension}`);
     const text = readFileSync(src, "utf8");
     const exists = existsSync(dest) || isSymlink(dest);
+    const staleQuestAgent = exists && !sameFile(dest, text) && existingAgentMatchesName(provider, name, dest);
     let action;
     if (exists && sameFile(dest, text)) action = "unchanged";
-    else if (exists && !force) action = "conflict";
+    else if (exists && !force && !(replaceStale && staleQuestAgent)) action = "conflict";
     else action = exists ? "replace" : "create";
     return { name, path: dest, action, text };
   });
@@ -208,6 +222,92 @@ export function installClaudeAgents(options = {}) {
   return installProviderAgents("claude", options);
 }
 
+export function nativeProjectRoot(cwd = process.cwd(), env = process.env) {
+  return projectRoot(cwd, env);
+}
+
+function questBin() {
+  return join(PLUGIN_ROOT, "bin", "quest");
+}
+
+function questRunBin() {
+  return join(PLUGIN_ROOT, "bin", "quest-run");
+}
+
+function shellQuote(arg) {
+  return /^[A-Za-z0-9_./:=@+-]+$/.test(arg) ? arg : `'${String(arg).replaceAll("'", "'\\''")}'`;
+}
+
+function providerRecommendation(provider, checks) {
+  const bad = (name) => checkByName({ checks }, name)?.ok === false;
+  const commandId = "<id>";
+  if (provider === "codex") {
+    const setupCheckNames = [
+      "version-sync",
+      "quest-cli-path",
+      "codex-cli",
+      "plugin-installed",
+      "plugin-version",
+      "hook-parser",
+      "single-neutral-skill-root",
+      "native-agents",
+    ];
+    const setupReady = setupCheckNames.every((name) => checkByName({ checks }, name)?.ok === true);
+    if (!setupReady) {
+      return {
+        key: "repair-first",
+        label: "repair Codex setup first",
+        available: false,
+        command: `${shellQuote(questBin())} codex doctor --fix`,
+        reason: "Codex setup checks must be green before Quest can print a trustworthy work handoff",
+      };
+    }
+    if (!bad("multi-agent-feature") && !bad("goals-feature")) {
+      return {
+        key: "native-subagents",
+        label: "native Codex quest-executor subagent",
+        available: true,
+        command: `${shellQuote(questBin())} codex work ${commandId} --dry-run`,
+        reason: "multi_agent, goals, Quest plugin, skill root, and native-agent template checks are green",
+      };
+    }
+    if (!bad("goals-feature")) {
+      return {
+        key: "quest-run-goal-required",
+        label: "headless Codex runner fallback with required goal tools",
+        available: true,
+        command: `${shellQuote(questRunBin())} ${commandId} --worker codex --codex-goal-mode require`,
+        reason: "Codex goal tools are available, but native multi-agent dispatch is not",
+      };
+    }
+    return {
+      key: "quest-run-goal-auto",
+      label: "headless Codex runner fallback with auto goal mode",
+      available: true,
+      command: `${shellQuote(questRunBin())} ${commandId} --worker codex --codex-goal-mode auto`,
+      reason: "Codex native goal mode is unavailable, so the runner must not require goal tools",
+    };
+  }
+
+  const setupReady = checks.every((c) => c.ok);
+  if (!setupReady) {
+    return {
+      key: "repair-first",
+      label: "repair Claude setup first",
+      available: false,
+      command: `${shellQuote(questBin())} claude doctor --fix`,
+      reason: "Claude setup checks must be green before Quest can print a trustworthy work handoff",
+    };
+  }
+  return {
+    key: "native-subagents",
+    label: "native Claude quest-executor subagent",
+    available: true,
+    command: `${shellQuote(questBin())} claude work ${commandId} --dry-run`,
+    reason: "Claude CLI, Quest plugin, and native-agent template checks are green",
+  };
+}
+
 function questCliPathCheck(cwd, env, versions) {
   const pathQuestVersion = runCmd("quest", ["--version"], { cwd, env });
   const pathVersion = pathQuestVersion.status === 0 ? pathQuestVersion.stdout.trim() : null;
@@ -243,7 +343,7 @@ function nativeAgentsCheck(provider, cwd, env) {
   }
   const agentDetail = [
     missing.length ? `missing: ${missing.join(", ")}` : null,
-    stale.length ? `stale (run install-agents --force): ${stale.join(", ")}` : null,
+    stale.length ? `stale (run doctor --fix or install-agents): ${stale.join(", ")}` : null,
   ].filter(Boolean).join("; ") || `installed ${cfg.label} templates current: ${Object.values(found).join(", ")}`;
   return check(
     "native-agents",
@@ -360,7 +460,7 @@ export function doctor({ cwd = process.cwd(), env = process.env } = {}) {
 
   checks.push(nativeAgentsCheck("codex", cwd, env));
 
-  return { ok: checks.every((c) => c.ok), checks };
+  return { ok: checks.every((c) => c.ok), checks, recommended_path: providerRecommendation("codex", checks) };
 }
 
 export function claudeDoctor({ cwd = process.cwd(), env = process.env } = {}) {
@@ -416,5 +516,115 @@ export function claudeDoctor({ cwd = process.cwd(), env = process.env } = {}) {
 
   checks.push(nativeAgentsCheck("claude", cwd, env));
 
-  return { ok: checks.every((c) => c.ok), checks };
+  return { ok: checks.every((c) => c.ok), checks, recommended_path: providerRecommendation("claude", checks) };
+}
+
+function checkByName(result, name) {
+  return result.checks.find((c) => c.name === name);
+}
+
+function cmdDetail(res) {
+  const text = [res.stdout, res.stderr, res.error?.message].filter(Boolean).join("\n").trim();
+  return text || `exit ${res.status ?? "unknown"}`;
+}
+
+function repairRecord(name, command, res, extra = {}) {
+  return {
+    name,
+    command: command.join(" "),
+    ok: res.status === 0,
+    detail: cmdDetail(res),
+    ...extra,
+  };
+}
+
+function runRepairCommand(cmd, args, { cwd, env }) {
+  return runCmd(cmd, args, { cwd, env });
+}
+
+function codexMarketplacePresent(cwd, env) {
+  const res = runCmd("codex", ["plugin", "marketplace", "list", "--json"], { cwd, env });
+  if (res.status !== 0) return { ok: false, present: false, res };
+  try {
+    const parsed = JSON.parse(res.stdout || "{}");
+    const marketplaces = Array.isArray(parsed.marketplaces) ? parsed.marketplaces : [];
+    return { ok: true, present: marketplaces.some((m) => m.name === "quest" || m.root?.includes("/quest")) };
+  } catch {
+    return { ok: false, present: false, res };
+  }
+}
+
+function providerPluginNeedsRepair(provider, result) {
+  const names = provider === "codex"
+    ? ["plugin-installed", "plugin-version", "hook-parser", "single-neutral-skill-root"]
+    : ["plugin-installed", "plugin-version"];
+  return names.some((name) => checkByName(result, name)?.ok === false);
+}
+
+function repairProviderPlugin(provider, before, { cwd, env }) {
+  const cliName = provider === "codex" ? "codex-cli" : "claude-cli";
+  if (!checkByName(before, cliName)?.ok || !providerPluginNeedsRepair(provider, before)) return [];
+
+  const repairs = [];
+  if (provider === "codex") {
+    const marketplace = codexMarketplacePresent(cwd, env);
+    if (!marketplace.ok) {
+      repairs.push(repairRecord("plugin-marketplace-list", ["codex", "plugin", "marketplace", "list", "--json"], marketplace.res));
+      return repairs;
+    }
+    if (!marketplace.present) {
+      const addMarketplaceArgs = ["plugin", "marketplace", "add", QUEST_CODEX_MARKETPLACE_SOURCE];
+      const addMarketplace = runRepairCommand("codex", addMarketplaceArgs, { cwd, env });
+      repairs.push(repairRecord("plugin-marketplace-add", ["codex", ...addMarketplaceArgs], addMarketplace));
+      if (addMarketplace.status !== 0) return repairs;
+    }
+    const upgrade = runRepairCommand("codex", ["plugin", "marketplace", "upgrade", "quest"], { cwd, env });
+    repairs.push(repairRecord("plugin-marketplace-upgrade", ["codex", "plugin", "marketplace", "upgrade", "quest"], upgrade));
+    if (upgrade.status !== 0) return repairs;
+    const addPlugin = runRepairCommand("codex", ["plugin", "add", "quest@quest"], { cwd, env });
+    repairs.push(repairRecord("plugin-add", ["codex", "plugin", "add", "quest@quest"], addPlugin));
+    return repairs;
+  }
+
+  const installed = checkByName(before, "plugin-installed")?.installed;
+  const subcommand = installed ? "update" : "install";
+  const res = runRepairCommand("claude", ["plugin", subcommand, "quest@quest"], { cwd, env });
+  repairs.push(repairRecord(`plugin-${subcommand}`, ["claude", "plugin", subcommand, "quest@quest"], res));
+  return repairs;
+}
+
+function repairProviderAgents(provider, before, { cwd, env }) {
+  if (checkByName(before, "native-agents")?.ok !== false) return [];
+  const result = installProviderAgents(provider, { scope: "project", force: false, replaceStale: true, cwd, env });
+  return [{
+    name: "native-agents",
+    command: `quest ${provider} install-agents --scope project`,
+    ok: result.ok,
+    detail: result.ok ? `${result.actions.map((a) => `${a.action} ${a.path}`).join("; ")}` : `conflicts: ${result.conflicts.map((c) => c.path).join(", ")}`,
+    result,
+  }];
+}
+
+function doctorForProvider(provider, options) {
+  if (provider === "codex") return doctor(options);
+  if (provider === "claude") return claudeDoctor(options);
+  throw new Error(`unknown provider "${provider}"`);
+}
+
+function doctorWithFix(provider, { cwd = process.cwd(), env = process.env } = {}) {
+  const before = doctorForProvider(provider, { cwd, env });
+  const repairs = [
+    ...repairProviderAgents(provider, before, { cwd, env }),
+    ...repairProviderPlugin(provider, before, { cwd, env }),
+  ];
+  const after = doctorForProvider(provider, { cwd, env });
+  return { ok: after.ok, checks: after.checks, recommended_path: after.recommended_path, repairs, before };
+}
+
+export function codexDoctorFix(options = {}) {
+  return doctorWithFix("codex", options);
+}
+
+export function claudeDoctorFix(options = {}) {
+  return doctorWithFix("claude", options);
 }

package/lib/graph.mjs

@@ -0,0 +1,82 @@
+const TERMINAL = new Set(["complete", "cancelled"]);
+
+function byId(quests) {
+  return new Map(quests.map((q) => [q.id, q]));
+}
+
+function prioritySort(a, b) {
+  return a.priority.localeCompare(b.priority) || a.id - b.id;
+}
+
+function dependencyIds(q) {
+  return Array.isArray(q.depends_on) && q.depends_on.every(Number.isInteger) ? q.depends_on : [];
+}
+
+function hasMalformedDependsOn(q) {
+  return "depends_on" in q && (!Array.isArray(q.depends_on) || q.depends_on.some((d) => !Number.isInteger(d)));
+}
+
+function openChildIds(quests, parentId) {
+  return quests
+    .filter((q) => q.parent === parentId && !TERMINAL.has(q.status))
+    .map((q) => q.id)
+    .sort((a, b) => a - b);
+}
+
+function queueBlockers(q, known, quests, epicIds) {
+  const reasons = [];
+  if (q.parent !== undefined && !known.has(q.parent)) reasons.push(`missing parent: #${q.parent}`);
+  if (hasMalformedDependsOn(q)) reasons.push("malformed depends_on: must be a list of quest ids");
+
+  const deps = dependencyIds(q);
+  const missingDeps = deps.filter((id) => !known.has(id));
+  if (missingDeps.length) reasons.push(`missing depends_on: ${missingDeps.map((id) => `#${id}`).join(", ")}`);
+
+  const incompleteDeps = deps.filter((id) => known.has(id) && known.get(id).status !== "complete");
+  if (incompleteDeps.length) reasons.push(`incomplete depends_on: ${incompleteDeps.map((id) => `#${id}`).join(", ")}`);
+
+  if (epicIds.has(q.id)) {
+    const open = openChildIds(quests, q.id);
+    if (open.length) reasons.push(`open children: ${open.map((id) => `#${id}`).join(", ")}`);
+  }
+  return reasons;
+}
+
+export function computeQueue(quests) {
+  const all = [...quests];
+  const known = byId(all);
+  const epicIds = new Set(all.filter((q) => q.parent !== undefined).map((q) => q.parent));
+  const workerReady = [];
+  const inlineCloseReadyEpics = [];
+  const blocked = [];
+
+  for (const q of all) {
+    if (q.status !== "todo") continue;
+    const reasons = queueBlockers(q, known, all, epicIds);
+    if (reasons.length) {
+      blocked.push({ quest: q, reasons });
+      continue;
+    }
+    if (epicIds.has(q.id)) inlineCloseReadyEpics.push(q);
+    else workerReady.push(q);
+  }
+
+  workerReady.sort(prioritySort);
+  inlineCloseReadyEpics.sort(prioritySort);
+  blocked.sort((a, b) => prioritySort(a.quest, b.quest));
+  return { workerReady, inlineCloseReadyEpics, blocked };
+}
+
+export function lintGraphReferences(quests) {
+  const known = byId(quests);
+  const problems = new Map(quests.map((q) => [q.id, []]));
+  for (const q of quests) {
+    if (q.parent !== undefined && !known.has(q.parent)) {
+      problems.get(q.id).push(`parent references unknown quest ${q.parent}`);
+    }
+    for (const dep of dependencyIds(q)) {
+      if (!known.has(dep)) problems.get(q.id).push(`depends_on references unknown quest ${dep}`);
+    }
+  }
+  return problems;
+}

package/lib/help.mjs

@@ -48,11 +48,12 @@ export const COMMANDS = {
   },
   list: {
     purpose: "List quests (filter by status, parent, or readiness)",
-    usage: "quest list [--status <s>] [--parent <id>] [--ready] [--json]",
+    usage: "quest list [--status <s>] [--parent <id>] [--ready|--queue] [--json]",
     flags: [
       ["--status <s>", "todo | in_progress | blocked | complete | cancelled"],
       ["--parent <id>", "children of an epic"],
-      ["--ready", "todo quests whose depends_on are all complete, excluding epics with open children (dispatch order)"],
+      ["--ready", "worker-dispatchable todo quests whose depends_on are complete, excluding epics"],
+      ["--queue", "worker-ready quests, inline-close-ready epics, and blocked queue reasons"],
       ["--json", "machine-readable output"],
     ],
     example: "quest list --ready",
@@ -138,33 +139,46 @@ 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]",
+    purpose: "Inspect, repair, install, open, or hand off Quest's native Codex integration",
+    usage: "quest codex doctor [--fix] [--json] | quest codex work <id> --dry-run | quest codex open [--dry-run] [-- <codex args>] | quest codex install-agents [--scope project|user] [--dry-run] [--force] [--json]",
     flags: [
       ["doctor", "check Codex CLI, multi-agent support, plugin install/version, hooks, skill roots, and native-agent templates"],
+      ["--fix", "repair missing/stale Quest agents and Quest plugin install/version when possible, then rerun doctor"],
+      ["work <id>", "run the health gate and print the native subagent or runner-fallback handoff"],
+      ["open", "repair/check setup, then launch interactive Codex from the project root"],
       ["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"],
+      ["--dry-run", "install-agents: preview writes; work/open: print the handoff or launch command without starting provider work"],
+      ["--force", "replace existing non-Quest agent files"],
       ["--json", "machine-readable output"],
     ],
-    example: "quest codex install-agents --scope project && quest codex doctor",
+    example: "quest codex doctor --fix && quest codex work 12 --dry-run",
   },
   claude: {
-    purpose: "Inspect or install Quest's native Claude Code integration",
-    usage: "quest claude doctor [--json] | quest claude install-agents [--scope project|user] [--dry-run] [--force] [--json]",
+    purpose: "Inspect, repair, install, open, or hand off Quest's native Claude Code integration",
+    usage: "quest claude doctor [--fix] [--json] | quest claude work <id> --dry-run | quest claude open [--dry-run] [-- <claude args>] | quest claude install-agents [--scope project|user] [--dry-run] [--force] [--json]",
     flags: [
       ["doctor", "check Claude CLI, plugin install/version, and native-agent templates"],
+      ["--fix", "repair missing/stale Quest agents and Quest plugin install/version when possible, then rerun doctor"],
+      ["work <id>", "run the health gate and print the native subagent handoff"],
+      ["open", "repair/check setup, then launch interactive Claude Code from the project root"],
       ["install-agents", "install quest-executor and quest-reviewer as native Claude Code custom agents"],
       ["--scope <s>", "project (default: .claude/agents at repo root) or user (~/.claude/agents)"],
-      ["--dry-run", "show intended agent writes without changing files"],
-      ["--force", "replace existing agent files"],
+      ["--dry-run", "install-agents: preview writes; work/open: print the handoff or launch command without starting provider work"],
+      ["--force", "replace existing non-Quest agent files"],
       ["--json", "machine-readable output"],
     ],
-    example: "quest claude install-agents --scope project && quest claude doctor",
+    example: "quest claude doctor --fix && quest claude work 12 --dry-run",
   },
 };
 
+const COMMAND_GROUPS = [
+  ["Setup and authoring", ["init", "create", "edit", "lint", "protocol"]],
+  ["Queue and work", ["list", "show", "start", "checkpoint", "runs"]],
+  ["Lifecycle", ["cancel", "reopen", "amend"]],
+  ["Provider handoff", ["codex", "claude"]],
+];
+
 export function renderCommandHelp(name) {
   const c = COMMANDS[name];
   const lines = [c.purpose, "", `Usage: ${c.usage}`];
@@ -178,53 +192,84 @@ export function renderCommandHelp(name) {
 }
 
 export function renderGeneralHelp() {
-  const lines = [INTRO, "", "Commands:"];
+  const lines = [INTRO, "", "Commands by workflow:"];
   const w = Math.max(...Object.keys(COMMANDS).map((k) => k.length));
-  for (const [name, c] of Object.entries(COMMANDS)) lines.push(`  quest ${name.padEnd(w)}  ${c.purpose}`);
+  const seen = new Set();
+  for (const [group, names] of COMMAND_GROUPS) {
+    lines.push("", `${group}:`);
+    for (const name of names) {
+      const c = COMMANDS[name];
+      seen.add(name);
+      lines.push(`  quest ${name.padEnd(w)}  ${c.purpose}`);
+    }
+  }
+  const ungrouped = Object.keys(COMMANDS).filter((name) => !seen.has(name));
+  if (ungrouped.length) {
+    lines.push("", "Other:");
+    for (const name of ungrouped) lines.push(`  quest ${name.padEnd(w)}  ${COMMANDS[name].purpose}`);
+  }
   lines.push("", "Run `quest <command> --help` for flags and a copy-pasteable example.", "Headless workers: see `quest-run --help`.");
   return lines.join("\n");
 }
 
-export function renderStatusOverview({ counts, ready, activeRuns, backend }) {
+function renderQuestSummary(q, { includeStatus = false } = {}) {
+  const status = includeStatus ? `[${q.status}] ` : "";
+  return `  ${q.id}. ${status}[${q.priority}] ${q.title}`;
+}
+
+export function renderStatusOverview({ counts, ready, activeRuns, backend, inFlightOrBlocked = [] }) {
   const lines = [`Quest store: ${backend} backend`];
   const parts = ["todo", "in_progress", "blocked", "complete", "cancelled"]
     .filter((s) => counts[s])
     .map((s) => `${counts[s]} ${s}`);
   lines.push(parts.length ? `Quests: ${parts.join(" · ")}` : "Quests: none yet");
+  lines.push(`Active runs: ${activeRuns}`);
+
+  lines.push("", "In flight / blocked:");
+  if (inFlightOrBlocked.length) {
+    for (const q of inFlightOrBlocked.slice(0, 3)) lines.push(renderQuestSummary(q, { includeStatus: true }));
+  } else {
+    lines.push("  none");
+  }
+
+  lines.push("", "Ready work:");
   if (ready.length) {
-    lines.push("", "Ready to work (dependencies met):");
-    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>`.");
+    for (const q of ready.slice(0, 3)) lines.push(renderQuestSummary(q));
+  } else {
+    lines.push("  none");
+  }
+
+  let next;
+  if (activeRuns > 0) {
+    next = "quest runs --active";
+  } else if (inFlightOrBlocked.length) {
+    next = `quest show ${inFlightOrBlocked[0].id} --json`;
+  } else if (ready.length) {
+    next = `quest show ${ready[0].id} --json`;
   } else if (!parts.length) {
-    lines.push("", "Next: create your first quest — see `quest create --help` (or use the $quest:plan skill).");
+    next = "quest create --help";
   } else {
-    lines.push("", "Nothing ready to start. `quest list` to see everything.");
+    next = "quest list --queue";
   }
-  if (activeRuns > 0) lines.push("", `Active headless runs: ${activeRuns} — inspect with \`quest runs --active\`.`);
+  lines.push("", `Next: \`${next}\``);
   return lines.join("\n");
 }
 
 export function renderNoStore() {
   return [
-    "No quest store found (searched for .quests/ from here upward).",
-    "",
-    "Get started:",
-    "  quest init            create a local store here",
-    "  quest init --backend github --repo owner/name",
+    "No quest store found (.quests/ not found from here upward).",
     "",
-    "Then: `quest create --help` shows how to author your first quest.",
+    "Next: `quest init`",
+    "GitHub-backed store: `quest init --backend github --repo owner/name`",
   ].join("\n");
 }
 
 export function renderInitNextSteps(backend, { agentsInstalled = true } = {}) {
   return [
     "",
-    "Store created. Next steps:",
-    ...(agentsInstalled ? ["  0. Restart agent sessions so newly installed project templates are loaded"] : []),
-    "  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",
-    ...(agentsInstalled ? [] : ["  Agent templates skipped; install later with `quest codex install-agents --scope project` and `quest claude install-agents --scope project`."]),
-    ...(backend === "github" ? ["", "Records live as GitHub issues; config and amendments stay local in .quests/."] : []),
+    `Store ready: ${backend} backend`,
+    ...(backend === "github" ? ["Records live as GitHub issues; config and amendments stay local in .quests/."] : []),
+    ...(agentsInstalled ? ["Agent templates installed. Restart agent sessions before using new project agents."] : ["Agent templates skipped."]),
+    `Next: \`${agentsInstalled ? "quest codex doctor --fix" : "quest create --help"}\``,
   ].join("\n");
 }

package/lib/runner.mjs

@@ -184,6 +184,16 @@ async function recordBlocked(storeDir, env, id, summary, validation) {
 // Option resolution: flag → record frontmatter → config defaults
 // ---------------------------------------------------------------------------
 
+function parseNumericFlag(flags, name, { integer = false, min = -Infinity, label = "number" } = {}) {
+  const raw = flags[name];
+  if (raw == null) return undefined;
+  const value = Number(raw);
+  if (typeof raw !== "string" || raw.trim() === "" || !Number.isFinite(value) || (integer && !Number.isInteger(value)) || value < min) {
+    throw new RunUsageError(`--${name} must be ${label} (got "${raw}")`);
+  }
+  return value;
+}
+
 function resolveOptions(front, config, flags) {
   const worker = flags.worker ?? front.worker ?? config.defaults.worker;
   if (!["claude", "codex"].includes(worker)) throw new RunUsageError(`--worker must be claude or codex (got "${worker}")`);
@@ -191,12 +201,12 @@ function resolveOptions(front, config, flags) {
   const recordModel = front.model && front.model !== "inherit" ? front.model : undefined;
   const model = flags.model ?? recordModel ?? wd.model;
   const effort = flags.effort ?? front.effort ?? (worker === "codex" ? wd.reasoning_effort : wd.effort);
-  const maxIterations = flags["max-iterations"] != null ? Number(flags["max-iterations"]) : front.max_iterations ?? config.defaults.max_iterations;
-  const maxCost = flags["max-cost"] != null ? Number(flags["max-cost"]) : front.max_cost ?? undefined;
-  const maxTokens = flags["max-tokens"] != null ? Number(flags["max-tokens"]) : undefined;
+  const maxIterations = parseNumericFlag(flags, "max-iterations", { integer: true, min: 1, label: "a positive integer" }) ?? front.max_iterations ?? config.defaults.max_iterations;
+  const maxCost = parseNumericFlag(flags, "max-cost", { min: 0, label: "a non-negative number" }) ?? front.max_cost ?? undefined;
+  const maxTokens = parseNumericFlag(flags, "max-tokens", { integer: true, min: 1, label: "a positive integer" });
   // Per-session wall-clock cap (seconds → ms). Flag > config default > 1800s.
-  // A non-positive value disables the timeout.
-  const sessionTimeoutSec = flags["session-timeout"] != null ? Number(flags["session-timeout"]) : config.defaults.session_timeout ?? 1800;
+  // A zero value disables the timeout.
+  const sessionTimeoutSec = parseNumericFlag(flags, "session-timeout", { min: 0, label: "a non-negative number" }) ?? config.defaults.session_timeout ?? 1800;
   const sessionTimeout = Number.isFinite(sessionTimeoutSec) && sessionTimeoutSec > 0 ? Math.round(sessionTimeoutSec * 1000) : 0;
   // Codex exec sandbox: flag → config defaults.codex.sandbox → workspace-write.
   // No silent escalation: the safe default stays workspace-write, and the value
@@ -563,7 +573,7 @@ function makeWorktree(repoRoot, id, title, io) {
 }
 
 async function runReady(storeDir, config, flags, io) {
-  const parallel = Math.max(1, flags.parallel != null ? Number(flags.parallel) : 1);
+  const parallel = parseNumericFlag(flags, "parallel", { integer: true, min: 1, label: "a positive integer" }) ?? 1;
   const isolate = flags.isolate;
   if (isolate && isolate !== "worktree") throw new RunUsageError(`--isolate only supports "worktree" (got "${isolate}")`);
   const repoRoot = dirname(storeDir);
@@ -573,29 +583,17 @@ async function runReady(storeDir, config, flags, io) {
   const skippedEpics = new Set();
   const inFlight = new Map();
 
-  const readyIds = async () => {
-    const { stdout, code } = await questCli(storeDir, io.env, ["list", "--ready", "--json"]);
-    if (code !== 0) return [];
-    try {
-      return JSON.parse(stdout).map((q) => q.id);
-    } catch {
-      return [];
-    }
-  };
-
-  // 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();
+  const queue = async () => {
+    const { stdout, code } = await questCli(storeDir, io.env, ["list", "--queue", "--json"]);
+    if (code !== 0) return { workerReady: [], inlineCloseReadyEpics: [] };
     try {
-      return new Set(JSON.parse(stdout).filter((q) => q.parent !== undefined).map((q) => q.parent));
+      const parsed = JSON.parse(stdout);
+      return {
+        workerReady: (parsed.worker_ready ?? []).map((q) => q.id),
+        inlineCloseReadyEpics: (parsed.inline_close_ready_epics ?? []).map((q) => q.id),
+      };
     } catch {
-      return new Set();
+      return { workerReady: [], inlineCloseReadyEpics: [] };
     }
   };
 
@@ -619,14 +617,13 @@ async function runReady(storeDir, config, flags, io) {
   };
 
   for (;;) {
-    const epics = await epicIds();
-    const ready = (await readyIds()).filter((id) => !done.has(id) && !inFlight.has(id) && !skippedEpics.has(id));
+    const q = await queue();
+    for (const id of q.inlineCloseReadyEpics.filter((id) => !skippedEpics.has(id))) {
+      skippedEpics.add(id);
+      io.errOut(`quest-run: quest ${id} is an inline-close-ready epic — 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.`);
+    }
+    const ready = q.workerReady.filter((id) => !done.has(id) && !inFlight.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);
     }