quest-loop 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -4,7 +4,41 @@ 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
+
+### Added
+- `quest codex doctor --fix` and `quest claude doctor --fix` now repair
+  Quest-owned native-agent templates and provider plugin install/version state,
+  then rerun the same doctor checks.
+- `quest codex open` and `quest claude open` now run the provider health gate
+  before launching the interactive provider from the project root.
+
+### Changed
+- Stale Quest agent templates are replaced without `--force`; unrelated custom
+  files still require explicit replacement.
 
 ## [0.3.4] — 2026-07-08
 

package/README.md

@@ -57,8 +57,8 @@ Install Quest's project-scoped Claude agent templates and verify the local
 Claude setup with:
 
 ```bash
-quest claude install-agents --scope project
-quest claude doctor
+quest claude doctor --fix
+quest claude open
 ```
 
 For local development against a checkout, point Claude Code at the repo directly
@@ -84,16 +84,19 @@ Verify the install with:
 
 ```bash
 codex plugin list --marketplace quest
-quest codex install-agents --scope project
-quest codex doctor
+quest codex doctor --fix
+quest codex open
 codex debug prompt-input "noop"
 ```
 
-`quest codex doctor` checks the installed plugin version, Codex `multi_agent`
-support, hook parser, neutral skill roots, and installed native-agent templates.
-`codex debug prompt-input "noop"` should not print any hook parse warnings.
+`quest codex doctor --fix` and `quest claude doctor --fix` install or refresh
+Quest-owned native-agent templates and repair the provider plugin install/version
+when the provider CLI supports it, then rerun doctor. `quest codex open` and
+`quest claude open` run the same health gate before launching the interactive
+provider. `codex debug prompt-input "noop"` should not print any hook parse
+warnings.
 
-#### Updating the Codex plugin
+#### Updating provider plugins
 
 Codex installs plugins from a marketplace snapshot. Pulling this Git repo or
 publishing a new tag is not enough to update the already-installed plugin cache.
@@ -103,10 +106,18 @@ Refresh the marketplace snapshot, then reinstall the plugin from it:
 codex plugin marketplace upgrade quest
 codex plugin add quest@quest
 codex plugin list --marketplace quest
-quest codex doctor
+quest codex doctor --fix
 ```
 
-Then start a new Codex thread. If the update contains hook changes, re-run:
+Claude updates through its plugin manager:
+
+```bash
+claude plugin update quest@quest
+quest claude doctor --fix
+```
+
+Then start a new provider session. If the Codex update contains hook changes,
+re-run:
 
 ```bash
 codex debug prompt-input "noop"
@@ -117,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
@@ -130,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. Show counts, active work, ready work, and the next command
+quest
 
-# 4. See what's ready to work (dependencies met)
-quest list --ready
+# 5. Read the quest before working it
+quest show 1 --json
 ```
 
 By default, `quest init` also installs project-scoped native agent templates for
@@ -145,8 +160,9 @@ both providers:
 - `.claude/agents/quest-executor.md`
 - `.claude/agents/quest-reviewer.md`
 
-Use `quest init --no-agents` when you only want the `.quests/` store. If an
-existing project agent template would be replaced, init fails before creating
+Use `quest init --no-agents` when you only want the `.quests/` store. Stale
+Quest-owned agent templates are replaced automatically. If an existing file is
+not recognizable as a Quest agent template, init fails before creating
 `.quests/`; inspect the conflicting files, run the explicit provider install
 command with `--force` only if you intend to replace them, then rerun
 `quest init`.
@@ -225,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) |
@@ -238,8 +255,8 @@ full base protocol lives in
 | `quest amend` | Append a numbered protocol amendment (retro output) |
 | `quest protocol` | Print the loop protocol + this store's local amendments |
 | `quest runs` | Show headless runner activity (from `.quests/runs.ndjson`) |
-| `quest codex` | Validate Codex-native setup and install Codex native agent templates |
-| `quest claude` | Validate Claude-native setup and install Claude native agent templates |
+| `quest codex` | Validate, repair, install, or open Codex-native setup |
+| `quest claude` | Validate, repair, install, or open Claude-native setup |
 
 ## quest-run (headless runner)
 

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

@@ -5,13 +5,14 @@ import { parseArgs } from "node:util";
 import { readFileSync, existsSync, writeFileSync, appendFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
 import { ConfigError, findStoreDir, loadConfig } from "./config.mjs";
 import { ContractError, lintRecord } from "./contract.mjs";
 import * as local from "./store-local.mjs";
 import * as github from "./store-github.mjs";
 import { openStore } from "./store.mjs";
 import { COMMANDS, renderCommandHelp, renderGeneralHelp, renderInitNextSteps, renderNoStore, renderStatusOverview } from "./help.mjs";
-import { claudeDoctor, doctor as codexDoctor, installAgents as installCodexAgents, installClaudeAgents, versionInfo } from "./codex-native.mjs";
+import { claudeDoctor, claudeDoctorFix, codexDoctorFix, doctor as codexDoctor, installAgents as installCodexAgents, installClaudeAgents, nativeProjectRoot, versionInfo } from "./codex-native.mjs";
 
 const PLUGIN_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -92,28 +93,161 @@ function preflightInitAgentInstall(cwd, env) {
   return plans;
 }
 
-async function runNativeSetupCommand(command, args, { out, cwd, env }, { label, doctor, install }) {
+function printDoctorResult(command, result, out) {
+  if (result.repairs?.length) {
+    out(`${command} doctor --fix: repairs`);
+    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`);
+}
+
+function parseOpenArgs(args) {
+  const forwarded = [];
+  let dryRun = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--") {
+      forwarded.push(...args.slice(i + 1));
+      break;
+    }
+    if (arg === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") return { help: true };
+    forwarded.push(arg);
+  }
+  return { dryRun, forwarded };
+}
+
+function shellQuote(arg) {
+  return /^[A-Za-z0-9_./:=@+-]+$/.test(arg) ? arg : `'${String(arg).replaceAll("'", "'\\''")}'`;
+}
+
+function openInvocation(command, cwd, env, forwarded) {
+  const root = nativeProjectRoot(cwd, env);
+  if (command === "codex") return { cmd: "codex", args: ["-C", root, ...forwarded], cwd };
+  if (command === "claude") return { cmd: "claude", args: forwarded, cwd: root };
+  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") {
     out(renderCommandHelp(command));
     return 0;
   }
   if (subcommand === "doctor") {
-    const p = parse(command, rest, {}, { positionals: 0 });
+    const p = parse(command, rest, { fix: { type: "boolean" } }, { positionals: 0 });
     if (p.help) {
       out(renderCommandHelp(command));
       return 0;
     }
-    const result = doctor({ cwd, env });
+    const result = p.values.fix ? doctorFix({ cwd, env }) : doctor({ cwd, env });
     if (p.values.json) out(JSON.stringify(result));
-    else {
-      for (const c of result.checks) out(`${c.ok ? "OK " : "ERR"} ${c.name}: ${c.detail}`);
-      out(result.ok ? `${command} doctor: OK` : `${command} doctor: problems found`);
-    }
+    else printDoctorResult(command, result, out);
     // 1 (generic diagnostic failure), not 5 — exit 5 is reserved for
     // ContractError (a quest contract violation), which a doctor finding is not.
     return result.ok ? 0 : 1;
   }
+  if (subcommand === "open") {
+    const p = parseOpenArgs(rest);
+    if (p.help) {
+      out(renderCommandHelp(command));
+      return 0;
+    }
+    const result = doctorFix({ cwd, env });
+    if (!result.ok) {
+      printDoctorResult(command, result, out);
+      out(`${command} open: not launching because doctor still reports problems`);
+      return 1;
+    }
+    const invocation = openInvocation(command, cwd, env, p.forwarded);
+    const rendered = [invocation.cmd, ...invocation.args].map(shellQuote).join(" ");
+    if (p.dryRun) {
+      out(`${command} open: health OK`);
+      out(`Would run: ${rendered}`);
+      return 0;
+    }
+    out(`${command} open: health OK; launching ${rendered}`);
+    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" },
@@ -183,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;
   }
 
@@ -308,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;
   },
@@ -319,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));
@@ -536,10 +702,10 @@ const HANDLERS = {
   },
 
   async codex(args, { out, cwd, env }) {
-    return runNativeSetupCommand("codex", args, { out, cwd, env }, { label: "Codex", doctor: codexDoctor, install: installCodexAgents });
+    return runNativeSetupCommand("codex", args, { out, cwd, env }, { label: "Codex", doctor: codexDoctor, doctorFix: codexDoctorFix, install: installCodexAgents });
   },
 
   async claude(args, { out, cwd, env }) {
-    return runNativeSetupCommand("claude", args, { out, cwd, env }, { label: "Claude", doctor: claudeDoctor, install: installClaudeAgents });
+    return runNativeSetupCommand("claude", args, { out, cwd, env }, { label: "Claude", doctor: claudeDoctor, doctorFix: claudeDoctorFix, install: installClaudeAgents });
   },
 };