quest-loop 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -4,7 +4,28 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [SemVer](https://semver.org/).
 
-## Unreleased
+## [0.3.6] — 2026-07-09
+
+### Added
+- `quest list --queue` now exposes worker-ready quests, inline-close-ready epics,
+  and blocked queue reasons as separate orchestration queues.
+- `quest lint --all` now reports missing parent and `depends_on` references
+  across local and GitHub-backed stores.
+- Provider `work --dry-run` commands now print native subagent handoffs or the
+  `quest-run` fallback command after running setup health checks.
+
+### Changed
+- Session-start status output and command help are more concise and focused on
+  the next operator action.
+- `$quest:plan` and `$quest:orchestrate` now document the v2 queue workflow and
+  explicit provider/model/effort handoffs more precisely.
+
+### Fixed
+- Malformed hand-edited `depends_on` metadata now stays a normal contract or
+  queue-blocking problem instead of crashing graph lint or entering
+  `worker_ready`.
+- Headless Codex fallback handoff commands now quote Quest binary paths that
+  contain spaces.
 
 ## [0.3.5] — 2026-07-08
 

package/README.md

@@ -128,7 +128,8 @@ you drive it from Claude Code, Codex, or a plain shell.
 
 ## Quickstart
 
-Create a store in your project, author a quest, check it, and work it:
+Create a store in your project, author a quest, check it, then use the compact
+dashboard to pick the next action:
 
 ```bash
 # 1. Create a quest store (.quests/) here
@@ -141,11 +142,14 @@ quest create --title "Add dark mode" \
   --done-when "\`npm test\` passes including new theme tests" \
   --validation "npm test"
 
-# 3. Check it against the contract spec
-quest lint --all
+# 3. Check the new quest against the contract spec
+quest lint 1
 
-# 4. See what's ready to work (dependencies met)
-quest list --ready
+# 4. Show counts, active work, ready work, and the next command
+quest
+
+# 5. Read the quest before working it
+quest show 1 --json
 ```
 
 By default, `quest init` also installs project-scoped native agent templates for
@@ -237,6 +241,7 @@ full base protocol lives in
 
 | Command | Purpose |
 |---|---|
+| bare `quest` | Show a compact dashboard with counts, active work, ready work, active runs, and the next command |
 | `quest init` | Create a quest store (`.quests/`) and install project-scoped Codex/Claude agent templates by default |
 | `quest create` | Create a new quest (the only way records are born) |
 | `quest list` | List quests (filter by status, parent, or readiness) |

package/hooks/session-start.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 // SessionStart hook (startup / clear / compact). When a `.quests/` store exists
 // at or above the session's cwd, write a short one-paragraph summary of in-flight
-// quests and active runs to stdout — Claude Code injects stdout as session
-// context. No store, a non-local backend, an empty store, or ANY error → a silent
-// no-op (exit 0). Reads only; no network and no child processes, so it stays fast.
+// local quests and active runs to stdout — Claude Code injects stdout as session
+// context. GitHub-backed stores get a no-network hint instead of live issue
+// counts. No store or ANY error → a silent no-op (exit 0). Reads only; no network
+// and no child processes, so it stays fast.
 
 import { writeSync } from "node:fs";
 import { findStoreDir, loadConfig } from "../lib/config.mjs";
@@ -24,25 +25,31 @@ function activeRunCount(storeDir) {
 }
 
 // One paragraph (<= ~3 lines): counts by status, up to 3 in-flight quests, the
-// active-run count, and the ready-list hint. Returns null when there is nothing
-// worth injecting (empty store).
+// active-run count, and one exact next command.
 function buildContext(storeDir) {
   const all = listQuests(storeDir);
-  if (!all.length) return null;
+  if (!all.length) return "Quest store (.quests): local backend, no quests.\nNext: run `quest create --help`.";
   const counts = {};
   for (const q of all) counts[q.status] = (counts[q.status] ?? 0) + 1;
   const countStr = STATUS_ORDER.filter((s) => counts[s]).map((s) => `${counts[s]} ${s}`).join(", ");
-  const inFlight = all
+  const inFlightQuests = all
     .filter((q) => q.status === "in_progress" || q.status === "blocked")
     .sort((a, b) => (a.status === b.status ? a.id - b.id : a.status === "in_progress" ? -1 : 1))
-    .slice(0, 3)
-    .map((q) => `#${q.id} ${q.title} [${q.status}]`);
+    .slice(0, 3);
+  const inFlight = inFlightQuests.map((q) => `#${q.id} ${q.title} [${q.status}]`);
   const lines = [`Quest store (.quests): ${all.length} quest${all.length === 1 ? "" : "s"} — ${countStr}.`];
   if (inFlight.length) lines.push(`In flight: ${inFlight.join("; ")}.`);
-  lines.push(`Active runs: ${activeRunCount(storeDir)}. Ready to work next: \`quest list --ready\`.`);
+  const next = inFlightQuests[0] ? `quest show ${inFlightQuests[0].id} --json` : "quest list --ready";
+  lines.push(`Active runs: ${activeRunCount(storeDir)}. Next: run \`${next}\`.`);
   return lines.join("\n");
 }
 
+function githubContext(config) {
+  const repo = config.github?.repo;
+  const scope = repo ? ` for ${repo}` : "";
+  return `Quest store (.quests): github backend${scope}. No GitHub request was made by this hook.\nNext: run \`quest list --ready\` when you need live issue state.`;
+}
+
 try {
   const raw = await readStdin();
   let payload = {};
@@ -50,7 +57,12 @@ try {
   const cwd = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
   const storeDir = findStoreDir(cwd, process.env);
   if (!storeDir) process.exit(0); // no store here — silent no-op, NOT an error
-  if (loadConfig(storeDir, process.env).backend !== "local") process.exit(0); // only local is readable today
+  const config = loadConfig(storeDir, process.env);
+  if (config.backend === "github") {
+    writeSync(1, githubContext(config) + "\n");
+    process.exit(0);
+  }
+  if (config.backend !== "local") process.exit(0);
   const context = buildContext(storeDir);
   if (context) writeSync(1, context + "\n");
   process.exit(0);

package/hooks/subagent-stop.mjs

@@ -6,25 +6,29 @@
 // A subagent counts as a quest-executor iff one of its transcript entries records
 // an actual *mutating* quest invocation — `quest start <id>` or `quest checkpoint
 // <id>` (under any binary prefix: `quest`, `./bin/quest`, `node bin/quest`) — as a
-// tool_use block whose shell command carries the marker. Read-only verbs
-// (`quest show <id> --json`, `list`, `protocol`, `runs`) are how reviewers and
-// orchestrators inspect a quest without owning it, so they must NEVER key
+// tool_use block whose shell command carries the marker, OR the native subagent
+// stop payload itself names the Quest-owned `quest-executor` agent and carries a
+// launch prompt in the orchestrator's narrow `work quest <id>` shape. Read-only
+// verbs (`quest show <id> --json`, `list`, `protocol`, `runs`) are how reviewers
+// and orchestrators inspect a quest without owning it, so they must NEVER key
 // detection: an agent whose transcript holds only read verbs is allowed silently.
-// The executor id comes from that first mutating invocation (deterministic,
-// transcript order) — including `quest checkpoint <id>`, because an executor
-// resuming an already-in_progress quest skips `quest start` and its first mutating
-// verb is the checkpoint. We parse the JSONL per-entry and inspect only tool_use
-// command inputs; prose, quoted skill text, examples, and echoed file contents live
-// in text blocks and tool_result content (never in a tool_use command), so
-// `quest start 12` / `quest checkpoint 12` examples in the skills can no longer key
-// detection. No mutating invocation → not our concern, allow silently. We then
+// The executor id comes from the first mutating invocation (deterministic,
+// transcript order) when present — including `quest checkpoint <id>`, because an
+// executor resuming an already-in_progress quest skips `quest start` and its first
+// mutating verb is the checkpoint. If no mutating command has run yet, a native
+// `quest-executor` launch prompt with an explicit quest id can still identify the
+// owner. We parse the JSONL per-entry and inspect only command inputs; prose,
+// quoted skill text, examples, and echoed file contents live in text blocks and
+// tool_result content (never in a command), so `quest start 12` / `quest checkpoint
+// 12` examples in the skills can no longer key detection. No mutating invocation
+// and no native executor launch id → not our concern, allow silently. We then
 // compare the quest's latest checkpoint against the subagent's start time (the
 // transcript's first timestamp): a checkpoint newer than start clears the stop; so
 // does a terminal store status (complete/blocked/cancelled) reached during the run.
 //
-// Conservative by construction: any missing/unreadable input or parse failure →
-// allow (exit 0), with a one-line stderr diagnostic. We never false-positive-block
-// unrelated subagents.
+// Conservative by construction: any missing input, unknown store/quest,
+// unreadable input, or parse failure → allow (exit 0). Expected allow paths stay
+// silent so unrelated or partially-shaped subagents do not surface hook noise.
 //
 // Block contract (Claude Code command hook): print {"decision":"block","reason"}
 // to stdout and exit 0. (Note: the {"ok":false,...} shape is for prompt/agent
@@ -41,6 +45,8 @@ import { loadQuest } from "../lib/store-local.mjs";
 // `git commit -m "quest checkpoint 1"`) does not falsely key executor detection.
 // Read verbs (show/list/protocol/runs) are deliberately absent.
 const MARKER = /^(?:node\s+)?(?:[.\w/@-]*\/)?quest\s+(start|checkpoint)\s+(\d+)/;
+const NATIVE_EXECUTOR_AGENT = "quest-executor";
+const NATIVE_WORK_PROMPT = /\bwork\s+quest\s+(\d+)\b/i;
 
 // Split a shell command into top-level segments on `&&`, `||`, `;`, `|`, and
 // newline, IGNORING any separator that sits inside single or double quotes. This
@@ -143,6 +149,20 @@ function commandOf(input) {
   return input && typeof input === "object" && typeof input.command === "string" ? input.command : null;
 }
 
+function firstString(...values) {
+  return values.find((v) => typeof v === "string" && v.trim());
+}
+
+function nativeExecutorQuestId(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const agentType = firstString(payload.agent_type, payload.agentType, payload.agent_name, payload.agentName, payload.name);
+  if (agentType !== NATIVE_EXECUTOR_AGENT) return null;
+  const prompt = firstString(payload.prompt, payload.task_prompt, payload.taskPrompt, payload.agent_prompt, payload.agentPrompt);
+  if (!prompt) return null;
+  const m = NATIVE_WORK_PROMPT.exec(prompt);
+  return m ? Number(m[1]) : null;
+}
+
 // The mutating-verb marker id from one transcript entry, considering only tool_use
 // command invocations. Assistant messages carry an array of content blocks; string
 // content (plain prose) and tool_result blocks (echoed output/file contents) are
@@ -194,29 +214,29 @@ try {
   try { payload = raw.trim() ? JSON.parse(raw) : {}; } catch { payload = {}; }
 
   const transcriptPath = payload.transcript_path;
-  if (typeof transcriptPath !== "string" || !transcriptPath) { diag("no transcript_path in payload; allowing"); allow(); }
+  if (typeof transcriptPath !== "string" || !transcriptPath) allow();
 
   let transcript;
   try { transcript = readFileSync(transcriptPath, "utf8"); }
   catch (err) { diag(`cannot read transcript (${err.code || err.message}); allowing`); allow(); }
 
-  const id = executorQuestId(transcript);
+  const id = executorQuestId(transcript) ?? nativeExecutorQuestId(payload);
   if (id == null) allow(); // no mutating quest invocation (read-only agent) — leave it alone, silently
 
   // Prefer an explicit start field if a future payload carries one; else the
   // transcript's first timestamp.
   const start = toMs(payload.start_time) ?? toMs(payload.started_at) ?? firstTimestamp(transcript);
-  if (start == null) { diag(`quest ${id}: could not determine subagent start time; allowing`); allow(); }
+  if (start == null) allow();
 
   const cwd = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
   let storeDir;
   try { storeDir = findStoreDir(cwd, process.env); }
-  catch (err) { diag(`quest ${id}: ${err.message}; allowing`); allow(); }
-  if (!storeDir) { diag(`quest ${id}: no store found from ${cwd}; allowing`); allow(); }
+  catch { allow(); }
+  if (!storeDir) allow();
 
   let quest;
   try { quest = loadQuest(storeDir, id); }
-  catch (err) { diag(`quest ${id}: ${err.message}; allowing`); allow(); }
+  catch { allow(); }
 
   // A checkpoint recorded after the subagent started clears the stop.
   const latestCp = quest.checkpoints.reduce((max, cp) => {

package/lib/cli.mjs

@@ -99,6 +99,10 @@ function printDoctorResult(command, result, out) {
     for (const r of result.repairs) out(`  ${r.ok ? "OK " : "ERR"} ${r.name}: ${r.command} (${r.detail})`);
   }
   for (const c of result.checks) out(`${c.ok ? "OK " : "ERR"} ${c.name}: ${c.detail}`);
+  if (result.recommended_path) {
+    const r = result.recommended_path;
+    out(`Recommendation: ${r.label} — ${r.command}`);
+  }
   out(result.ok ? `${command} doctor: OK` : `${command} doctor: problems found`);
 }
 
@@ -132,6 +136,54 @@ function openInvocation(command, cwd, env, forwarded) {
   throw new Error(`unknown provider "${command}"`);
 }
 
+function questCommandPrelude(cwd, env) {
+  const root = nativeProjectRoot(cwd, env);
+  return [
+    `cd ${shellQuote(root)}`,
+    `export PATH=${shellQuote(join(PLUGIN_ROOT, "bin"))}:$PATH`,
+    "quest --version",
+    "git status --short --branch",
+  ];
+}
+
+function codexNativePrompt(id) {
+  return "First call create_goal with: quest " + id +
+    " has a new checkpoint whose quest_status is complete or blocked in `quest show " + id +
+    " --json`; verify with get_goal; work quest " + id +
+    " per $quest:work; only call update_goal(status=\"complete\") after the checkpoint exists.";
+}
+
+function claudeNativePrompt(id) {
+  return "/goal quest " + id +
+    " has a new checkpoint whose quest_status is complete or blocked in `quest show " + id +
+    " --json`\nWork quest " + id + " per $quest:work.";
+}
+
+function renderWorkHandoff(command, id, recommendation, cwd, env) {
+  const lines = [
+    `${command} work: recommended path: ${recommendation.label}`,
+    `Reason: ${recommendation.reason}`,
+    "",
+    "Quest command prelude:",
+    ...questCommandPrelude(cwd, env).map((line) => `  ${line}`),
+    "",
+  ];
+  if (recommendation.key === "native-subagents") {
+    lines.push(
+      command === "codex" ? "Codex native subagent handoff:" : "Claude native subagent handoff:",
+      "  agent_type: quest-executor",
+      "  prompt:",
+      ...String(command === "codex" ? codexNativePrompt(id) : claudeNativePrompt(id)).split("\n").map((line) => `    ${line}`),
+    );
+  } else {
+    lines.push(
+      "Headless fallback command:",
+      `  ${recommendation.command.replace("<id>", String(id))}`,
+    );
+  }
+  return lines.join("\n");
+}
+
 async function runNativeSetupCommand(command, args, { out, cwd, env }, { label, doctor, doctorFix, install }) {
   const [subcommand, ...rest] = args;
   if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
@@ -174,6 +226,28 @@ async function runNativeSetupCommand(command, args, { out, cwd, env }, { label,
     const res = spawnSync(invocation.cmd, invocation.args, { cwd: invocation.cwd, env, stdio: "inherit" });
     return typeof res.status === "number" ? res.status : 1;
   }
+  if (subcommand === "work") {
+    const p = parse(command, rest, { "dry-run": { type: "boolean" } }, { positionals: 1 });
+    if (p.help) {
+      out(renderCommandHelp(command));
+      return 0;
+    }
+    const rawId = p.positionals[0];
+    if (!rawId || !/^\d+$/.test(rawId)) throw new UsageError("a numeric quest id is required", { command });
+    if (!p.values["dry-run"]) {
+      throw new UsageError(`${command} work only supports --dry-run; launching provider sessions is out of scope`, { command });
+    }
+    const result = doctor({ cwd, env });
+    if (!result.recommended_path?.available) {
+      printDoctorResult(command, result, out);
+      out(`${command} work: not printing a handoff because doctor still reports setup problems`);
+      return 1;
+    }
+    if (!result.ok) printDoctorResult(command, result, out);
+    else out(`${command} work: health OK`);
+    out(renderWorkHandoff(command, rawId, result.recommended_path, cwd, env));
+    return 0;
+  }
   if (subcommand === "install-agents") {
     const p = parse(command, rest, {
       scope: { type: "string", default: "project" },
@@ -243,7 +317,8 @@ async function dispatch(argv, ctx) {
     const runs = local.readRuns(storeDir);
     const ended = new Set(runs.filter((r) => r.event === "run_ended").map((r) => r.run_id));
     const active = runs.filter((r) => r.event === "run_started" && !ended.has(r.run_id)).length;
-    out(renderStatusOverview({ counts, ready: store.readyQuests(), activeRuns: active, backend: config.backend }));
+    const inFlightOrBlocked = all.filter((q) => q.status === "in_progress" || q.status === "blocked");
+    out(renderStatusOverview({ counts, ready: store.readyQuests(), activeRuns: active, backend: config.backend, inFlightOrBlocked }));
     return 0;
   }
 
@@ -368,8 +443,8 @@ const HANDLERS = {
     if (p.values.json) out(JSON.stringify({ ok: true, id: created.id, path: created.path }));
     else {
       out(`Created quest ${created.id}: ${v.title}`);
-      out(`  record: ${created.path}`);
-      out(`  next:   quest lint ${created.id} && quest show ${created.id}`);
+      out(`Record: ${created.path}`);
+      out(`Next: \`quest lint ${created.id}\``);
     }
     return 0;
   },
@@ -379,10 +454,41 @@ const HANDLERS = {
       status: { type: "string" },
       parent: { type: "string" },
       ready: { type: "boolean" },
+      queue: { type: "boolean" },
     });
     if (p.help) return void out(renderCommandHelp("list")) ?? 0;
+    if (p.values.ready && p.values.queue) throw new UsageError("--ready and --queue are mutually exclusive", { command: "list" });
+    if (p.values.queue && (p.values.status || p.values.parent)) throw new UsageError("--queue cannot be combined with --status or --parent", { command: "list" });
     const config = getStore(cwd, env);
     const store = openStore(config, { env });
+    if (p.values.queue) {
+      const q = store.queueState();
+      const payload = {
+        worker_ready: q.workerReady,
+        inline_close_ready_epics: q.inlineCloseReadyEpics,
+        blocked: q.blocked.map((b) => ({ quest: b.quest, reasons: b.reasons })),
+      };
+      if (p.values.json) {
+        out(JSON.stringify(payload));
+      } else {
+        const lines = [];
+        const pushQuest = (quest) => lines.push(`${String(quest.id).padStart(3)} [${quest.priority}] ${quest.status.padEnd(11)} ${quest.title}`);
+        lines.push("Worker-ready quests:");
+        if (payload.worker_ready.length) payload.worker_ready.forEach(pushQuest);
+        else lines.push("  (none)");
+        lines.push("", "Inline-close-ready epics:");
+        if (payload.inline_close_ready_epics.length) payload.inline_close_ready_epics.forEach(pushQuest);
+        else lines.push("  (none)");
+        lines.push("", "Blocked from queue:");
+        if (payload.blocked.length) {
+          for (const b of payload.blocked) lines.push(`${String(b.quest.id).padStart(3)} ${b.quest.title} — ${b.reasons.join("; ")}`);
+        } else {
+          lines.push("  (none)");
+        }
+        for (const line of lines) out(line);
+      }
+      return 0;
+    }
     let quests = p.values.ready ? store.readyQuests() : store.listQuests();
     if (p.values.status) quests = quests.filter((q) => q.status === p.values.status);
     if (p.values.parent) quests = quests.filter((q) => q.parent === Number(p.values.parent));

package/lib/codex-native.mjs

@@ -226,6 +226,88 @@ 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;
@@ -378,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 } = {}) {
@@ -434,7 +516,7 @@ 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) {
@@ -536,7 +618,7 @@ function doctorWithFix(provider, { cwd = process.cwd(), env = process.env } = {}
     ...repairProviderPlugin(provider, before, { cwd, env }),
   ];
   const after = doctorForProvider(provider, { cwd, env });
-  return { ok: after.ok, checks: after.checks, repairs, before };
+  return { ok: after.ok, checks: after.checks, recommended_path: after.recommended_path, repairs, before };
 }
 
 export function codexDoctorFix(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,37 +139,46 @@ export const COMMANDS = {
     example: "quest runs --active",
   },
   codex: {
-    purpose: "Inspect, repair, install, or open Quest's native Codex integration",
-    usage: "quest codex doctor [--fix] [--json] | quest codex open [--dry-run] [-- <codex args>] | 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"],
+      ["--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 doctor --fix && quest codex open",
+    example: "quest codex doctor --fix && quest codex work 12 --dry-run",
   },
   claude: {
-    purpose: "Inspect, repair, install, or open Quest's native Claude Code integration",
-    usage: "quest claude doctor [--fix] [--json] | quest claude open [--dry-run] [-- <claude args>] | 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"],
+      ["--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 doctor --fix && quest claude open",
+    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}`];
@@ -182,55 +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"] : []),
-    ...(agentsInstalled ? ["  1. Repair/check providers: quest codex doctor --fix  (or quest claude doctor --fix)"] : []),
-    ...(agentsInstalled ? ["  2. Open provider:          quest codex open        (or quest claude open)"] : []),
-    `  ${agentsInstalled ? "3" : "1"}. Author a quest:       quest create --help   (or $quest:plan in your agent session)`,
-    `  ${agentsInstalled ? "4" : "2"}. Check it:             quest lint --all`,
-    `  ${agentsInstalled ? "5" : "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);
     }

package/lib/store-github.mjs

@@ -31,6 +31,7 @@ import {
   serializeRecord,
 } from "./contract.mjs";
 import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.mjs";
+import { computeQueue, lintGraphReferences } from "./graph.mjs";
 import { NotFoundError } from "./store-local.mjs";
 
 export class GhError extends Error {
@@ -268,20 +269,15 @@ export function listQuests(repo, env) {
   });
 }
 
-// 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.
+// Same shared queue rule as store-local.readyQuests, over the remote list.
+// readyQuests returns only worker-dispatchable quests; inline-close-ready epics
+// are exposed separately by queueState.
 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" && !openParents.has(q.id) && (q.depends_on ?? []).every((d) => done.has(d)))
-    .sort((a, b) => a.priority.localeCompare(b.priority) || a.id - b.id);
+  return queueState(repo, env).workerReady;
+}
+
+export function queueState(repo, env) {
+  return computeQueue(listQuests(repo, env));
 }
 
 export function createQuest(repo, defaults, fields, sections, env) {
@@ -433,14 +429,20 @@ export function editQuest(repo, id, { addDoneWhen = [], addMilestone = [], addCo
 
 export function lintAll(repo, env) {
   const results = [];
+  const valid = [];
   for (const issue of listIssues(repo, env)) {
     try {
       const rec = reconstruct(issue);
       results.push({ file: rec.file, id: rec.front.id, problems: lintRecord(rec, { filename: rec.file }) });
+      valid.push({ ...rec.front, file: rec.file });
     } catch (err) {
       results.push({ file: `#${issue.number}`, id: issue.number ?? null, problems: [err.message] });
     }
   }
+  const graphProblems = lintGraphReferences(valid);
+  for (const result of results) {
+    if (result.id !== null) result.problems.push(...(graphProblems.get(result.id) ?? []));
+  }
   return results;
 }
 

package/lib/store-local.mjs

@@ -5,6 +5,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, writeFileSync, statSync, appendFileSync } from "node:fs";
 import { join, basename } from "node:path";
 import { ContractError, appendToSection, appendUnderCheckpoints, assertReopen, assertTransition, lintRecord, makeCheckpoint, nowIso, parseRecord, recordFilename, renderBody, serializeRecord, CHECKPOINT_MARKER } from "./contract.mjs";
+import { computeQueue, lintGraphReferences } from "./graph.mjs";
 
 export class NotFoundError extends Error {
   constructor(id) {
@@ -83,18 +84,11 @@ 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" && !openParents.has(q.id) && (q.depends_on ?? []).every((d) => done.has(d)))
-    .sort((a, b) => a.priority.localeCompare(b.priority) || a.id - b.id);
+  return queueState(storeDir).workerReady;
+}
+
+export function queueState(storeDir) {
+  return computeQueue(listQuests(storeDir));
 }
 
 export function createQuest(storeDir, defaults, fields, bodySections) {
@@ -238,16 +232,22 @@ export function readRuns(storeDir) {
 
 export function lintAll(storeDir) {
   const results = [];
+  const valid = [];
   for (const file of recordFiles(storeDir)) {
     const text = readFileSync(join(questsDir(storeDir), file), "utf8");
     try {
       const record = parseRecord(text);
       const problems = lintRecord(record, { filename: file });
       results.push({ file, id: record.front.id, problems });
+      valid.push({ ...record.front, file });
     } catch (err) {
       results.push({ file, id: null, problems: [err.message] });
     }
   }
+  const graphProblems = lintGraphReferences(valid);
+  for (const result of results) {
+    if (result.id !== null) result.problems.push(...(graphProblems.get(result.id) ?? []));
+  }
   return results;
 }
 

package/lib/store.mjs

@@ -15,6 +15,7 @@ export function openStore(config, ctx = {}) {
       loadQuest: (id) => github.loadQuest(repo, id, env),
       listQuests: () => github.listQuests(repo, env),
       readyQuests: () => github.readyQuests(repo, env),
+      queueState: () => github.queueState(repo, env),
       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),
@@ -29,6 +30,7 @@ export function openStore(config, ctx = {}) {
     loadQuest: (id) => local.loadQuest(dir, id),
     listQuests: () => local.listQuests(dir),
     readyQuests: () => local.readyQuests(dir),
+    queueState: () => local.queueState(dir),
     startQuest: (id) => local.startQuest(dir, id),
     appendCheckpoint: (id, cp) => local.appendCheckpoint(dir, id, cp),
     cancelQuest: (id, reason) => local.cancelQuest(dir, id, reason),

package/lib/workers.mjs

@@ -353,7 +353,7 @@ export const codex = {
     if (!sawGoal && opts.codexGoalMode === "require") {
       correctiveResume = true;
       resumes += 1;
-      const corr = this.buildResume(questRecord, config, opts, "--last", CODEX_CREATE_GOAL_CORRECTION(opts.id));
+      const corr = this.buildResume(questRecord, config, opts, sessionId || "--last", CODEX_CREATE_GOAL_CORRECTION(opts.id));
       const cres = await runSegment(corr);
       if (codexUsedCreateGoal(cres.events || [])) sawGoal = true;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quest-loop",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Goal-loop engineering for coding agents: quest contracts, iterative execution with evidence checkpoints, Claude + Codex workers. Ships the `quest` store CLI and the `quest-run` headless runner.",
   "type": "module",
   "engines": { "node": ">=20" },

package/skills/orchestrate/SKILL.md

@@ -18,9 +18,16 @@ trails, and escalations only where a human ruling is genuinely needed.
 
 1. **Adopt state** (especially at session start):
    ```bash
-   quest list --ready --json   # the dispatch queue (deps met, priority order)
+   quest list --queue --json   # orchestration state: worker_ready + inline_close_ready_epics
    quest runs --active         # headless runners that outlived prior sessions
    ```
+   `worker_ready` is the worker dispatch queue (deps met, priority order);
+   `inline_close_ready_epics` is the set of epics you close yourself after
+   verifying children and the epic validation loop. `quest list --ready --json`
+   remains a dispatch-only shortcut for `worker_ready`.
+   When the checkout, plugin cache, and installed package may differ, run the
+   checkout binary (`./bin/quest`) or verify `PATH` with `quest --version`
+   before trusting queue or dispatch behavior.
    For an implementation accepted from `$quest:plan` in Codex Plan Mode, stay in
    this orchestrator role. Do not implement product code inline; create/lint the
    quest records if needed, then dispatch workers.
@@ -31,7 +38,7 @@ trails, and escalations only where a human ruling is genuinely needed.
    - In Claude Code, start the turn with `/goal` using the same condition.
    If native goal mode is unavailable, say so and keep the Quest checkpoint
    trail as the hard stop signal; do not pretend a goal was set.
-3. **Dispatch** each ready quest per its record:
+3. **Dispatch** each `worker_ready` quest per its record:
    - In Codex, the default path is native subagents for both serial and
      parallel waves. If `spawn_agent` is not visible, call `tool_search` once
      for subagent tools before choosing any fallback. When available, spawn:
@@ -73,16 +80,17 @@ trails, and escalations only where a human ruling is genuinely needed.
      re-parent the original honestly.
    - **escalate-to-human** — surface human-only decisions verbatim. Never
      guess a ruling the human should make.
-7. **Wave done?** When `quest list --ready` empties and nothing is in flight:
-   run `$quest:retro` before starting the next wave.
+7. **Wave done?** When `quest list --queue --json` shows no `worker_ready` or
+   `inline_close_ready_epics`, and nothing is in flight, run `$quest:retro` (read skill `$quest:retro`) before starting the next wave.
 
 ## Closing an epic
 
 An epic is an ordinary quest that other quests name as `parent`. It is **never
-dispatched to a worker**: `quest list --ready` gates it out while any child is
-non-terminal, and `quest-run --ready` refuses it even once every child is
-terminal (a direct `quest-run <id>` on an epic still runs, but don't — it burns
-a worker on pure verification). Close it inline yourself, spending zero worker
+dispatched to a worker**: it does not belong in `worker_ready`, and
+`quest-run --ready` refuses it even once every child is terminal (a direct
+`quest-run <id>` on an epic still runs, but don't — it burns a worker on pure
+verification). Once it is closeable, `quest list --queue --json` reports it in
+`inline_close_ready_epics`; close it inline yourself, spending zero worker
 tokens:
 
 1. **Verify the children are genuinely done:**
@@ -119,7 +127,8 @@ quest reopen <id> --reason "review found npm audit criticals after completion"
 This flips `complete → in_progress` and appends an audited checkpoint carrying
 `reopen_reason`, so the loop keeps custody of the defect trail. Then dispatch the
 quest directly by id (`quest-run <id>` or a `quest-executor` subagent) — reopened
-quests are `in_progress`, so they do **not** re-appear in `quest list --ready`.
+quests are `in_progress`, so they do **not** re-appear in `worker_ready` or
+`quest list --ready`.
 Reopening a child of a **complete** parent epic is allowed (a stderr warning, not
 a block); you then rule whether the epic's completion verdict is falsified and,
 if so, reopen the epic too. `cancelled` is fully terminal — file a new quest.
@@ -139,7 +148,7 @@ genuinely done.
 ## Worked example
 
 ```bash
-quest list --ready --json     # → [{"id":12,"worker":"claude"…},{"id":13,"worker":"codex"…}]
+quest list --queue --json     # → {"worker_ready":[{"id":12…},{"id":13…}],"inline_close_ready_epics":[]}
 # 12 → spawn quest-executor with a child /goal or create_goal prompt
 # 13 → spawn quest-executor too; use quest-run only if native subagents are unavailable
 # …executor stops →

package/skills/plan/SKILL.md

@@ -27,14 +27,16 @@ extra context.
 In Codex Plan Mode, do **not** implement product code after the user accepts a
 plan. The same parent agent/session that processes `$quest:plan` owns the
 handoff: make the quest records real, then adopt `$quest:orchestrate` by
-default.
+default when the user asks to implement the plan. The parent session never uses
+`$quest:work <id>` after a Plan Mode handoff unless the user explicitly asks to.
 
 1. Create or confirm the quest records with `quest create` and `quest lint`.
 2. If the user accepted a plan and asked to implement it, the same parent
    session becomes `$quest:orchestrate`, not `$quest:work`. Do not start editing
-   product code in the parent session.
-3. In `$quest:orchestrate`, set the orchestrator goal for the wave, then spawn
-   goal-mode workers.
+   product code in the parent session. Read skill `$quest:orchestrate` and follow its rules for dispatching workers and closing epics inline.
+3. In `$quest:orchestrate`, inspect `quest list --queue --json`, set the
+   orchestrator goal for the wave, then spawn goal-mode workers for
+   `worker_ready` quests.
 4. Stop after listing the ready quest ids and validation commands only when the
    user explicitly asked for create-only/no-dispatch behavior such as "only
    create quests", "do not dispatch", or "stop after planning".
@@ -46,8 +48,15 @@ unless the user explicitly asks to bypass orchestration for a genuinely small
 single quest.
 
 For epics: create the parent first, then children with `--parent <id>` and
-`--depends-on` expressing the real order. `quest list --ready` becomes the
-dispatch queue — that is the whole wave mechanic.
+`--depends-on` expressing the real order. `quest list --queue --json` shows the
+wave order: `worker_ready` quests are dispatched, and
+`inline_close_ready_epics` are closed inline by the orchestrator after children
+finish. `quest list --ready` remains only the dispatch shortcut for
+`worker_ready`.
+
+When local checkout, plugin cache, and installed package versions can differ,
+author and lint with the checkout binary (`./bin/quest`) or verify `PATH` with
+`quest --version` before relying on queue semantics or generated records.
 
 Keep the **epic itself thin**. Its Done-when is **integration-level only**: it
 checks that the children compose into a working whole (the end-to-end behavior,
@@ -104,4 +113,4 @@ quest lint 12   # always, before dispatch
 
 **Next:** dispatch with `$quest:orchestrate`. Only work it yourself via
 `$quest:work <id>` for genuinely small inline work outside Plan Mode and outside
-an accepted Plan Mode handoff. Rules and vocabulary: `$quest:protocol`.
+an accepted Plan Mode handoff, when user explicitly asked for it. Rules and vocabulary: `$quest:protocol`.