quest-loop 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -6,6 +6,30 @@ All notable changes to this project are documented here. The format follows
 
 ## Unreleased
 
+## [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
+
+### Changed
+- `quest codex install-agents` and `quest claude install-agents` now allow
+  `--force` to write through symlinked agent template files, while continuing to
+  refuse symlinked provider agent directories.
+
+### Added
+- Added a Quest plan-exit reminder hook that nudges accepted `$quest:plan`
+  handoffs toward `$quest:orchestrate` rather than direct implementation.
+
 ## [0.3.3] — 2026-07-08
 
 ### Changed

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"
@@ -145,12 +156,17 @@ 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`.
 
+Agent template files may be symlinks; when you use `--force`, the install writes
+through those file symlinks. Keep `.codex/agents` and `.claude/agents` as real
+directories rather than symlinking the whole directory.
+
 Project-scoped agent templates install at the Git repository root. For a nested
 quest store, run `quest init --no-agents` in the nested directory and set
 `QUEST_DIR` for agents launched from elsewhere, or initialize from the repo root.
@@ -234,8 +250,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/hooks.json

@@ -62,6 +62,33 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "root=\"${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}\"; [ -n \"$root\" ] && node \"$root/hooks/plan-exit-reminder.mjs\"",
+            "commandWindows": "if defined CODEX_PLUGIN_ROOT (node \"%CODEX_PLUGIN_ROOT%\\hooks\\plan-exit-reminder.mjs\") else if defined CLAUDE_PLUGIN_ROOT (node \"%CLAUDE_PLUGIN_ROOT%\\hooks\\plan-exit-reminder.mjs\")",
+            "timeout": 10,
+            "statusMessage": "Preparing quest orchestration reminder"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "root=\"${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}\"; [ -n \"$root\" ] && node \"$root/hooks/plan-exit-reminder.mjs\"",
+            "commandWindows": "if defined CODEX_PLUGIN_ROOT (node \"%CODEX_PLUGIN_ROOT%\\hooks\\plan-exit-reminder.mjs\") else if defined CLAUDE_PLUGIN_ROOT (node \"%CLAUDE_PLUGIN_ROOT%\\hooks\\plan-exit-reminder.mjs\")",
+            "timeout": 10,
+            "statusMessage": "Checking quest plan handoff"
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/plan-exit-reminder.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Plan-exit reminder hook. When a Quest-generated plan handoff is accepted,
+// remind the parent session that the next run is orchestration, not direct
+// implementation. Anything uncertain is a silent no-op.
+
+import { writeSync } from "node:fs";
+
+const REMINDER = [
+  "Quest plan handoff accepted.",
+  "This run is about orchestration, not direct implementation:",
+  "create or confirm the quest records, run `quest lint`, then switch to `$quest:orchestrate` to dispatch workers, verify checkpoints, and close the wave.",
+].join(" ");
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function hookEventName(payload) {
+  return payload?.hook_event_name ?? payload?.hookEventName ?? "";
+}
+
+function toolName(payload) {
+  return payload?.tool_name ?? payload?.toolName ?? payload?.tool?.name ?? "";
+}
+
+function lastAssistantMessage(payload) {
+  const value = payload?.last_assistant_message ?? payload?.lastAssistantMessage;
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") return JSON.stringify(value);
+  return "";
+}
+
+function questPlanHandoff(text) {
+  if (!text) return false;
+  const hasQuestPlan = /(?:\$?quest:plan\b|\bquest create\b|\bquest lint\b|<proposed_plan>)/i.test(text);
+  const hasOrchestrate = /(?:\$?quest:orchestrate\b|\borchestration\b|\borchestrator\b)/i.test(text);
+  return hasQuestPlan && hasOrchestrate;
+}
+
+function postToolUseText(payload) {
+  const parts = [];
+  for (const key of ["tool_input", "toolInput", "tool_response", "toolResponse"]) {
+    const value = payload?.[key];
+    if (typeof value === "string") parts.push(value);
+    else if (value && typeof value === "object") parts.push(JSON.stringify(value));
+  }
+  return parts.join("\n");
+}
+
+function shouldRemind(payload) {
+  const event = hookEventName(payload);
+  if (event === "PostToolUse" && toolName(payload) === "ExitPlanMode") {
+    return questPlanHandoff(postToolUseText(payload));
+  }
+  if (event === "Stop") {
+    return questPlanHandoff(lastAssistantMessage(payload));
+  }
+  return false;
+}
+
+try {
+  const raw = await readStdin();
+  let payload = {};
+  try { payload = raw.trim() ? JSON.parse(raw) : {}; } catch { payload = {}; }
+  if (shouldRemind(payload)) writeSync(1, JSON.stringify({ systemMessage: REMINDER }) + "\n");
+  process.exit(0);
+} catch {
+  process.exit(0);
+}

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,87 @@ 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}`);
+  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}"`);
+}
+
+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 === "install-agents") {
     const p = parse(command, rest, {
       scope: { type: "string", default: "project" },
@@ -136,9 +196,9 @@ async function runNativeSetupCommand(command, args, { out, cwd, env }, { label,
     // A real run refuses to overwrite; a --dry-run PREVIEWS the conflict
     // (its whole purpose) rather than erroring before showing the plan.
     if (!result.ok && !isDry) {
-      const symlinkConflicts = result.conflicts.filter((c) => c.reason === "symlink");
-      if (symlinkConflicts.length) {
-        throw new UsageError(`refusing to write agent templates through symlinked path: ${symlinkConflicts.map((c) => c.path).join(", ")}`, { command });
+      const symlinkDirConflicts = result.conflicts.filter((c) => c.reason === "symlink-directory");
+      if (symlinkDirConflicts.length) {
+        throw new UsageError(`refusing to write agent templates through symlinked directory: ${symlinkDirConflicts.map((c) => c.path).join(", ")}`, { command });
       }
       const conflicts = result.conflicts.map((c) => c.path).join(", ");
       throw new UsageError(`agent file already exists; pass --force to replace: ${conflicts}`, { command });
@@ -147,7 +207,12 @@ async function runNativeSetupCommand(command, args, { out, cwd, env }, { label,
     else {
       out(`${isDry ? "Would install" : "Installed"} ${label} agents to ${result.target}`);
       for (const a of result.actions) out(`  ${a.action.padEnd(9)} ${a.path}`);
-      if (!result.ok) out(`  conflicts present — pass --force to replace: ${result.conflicts.map((c) => c.path).join(", ")}`);
+      if (!result.ok) {
+        const symlinkDirConflicts = result.conflicts.filter((c) => c.reason === "symlink-directory");
+        if (symlinkDirConflicts.length) out(`  symlinked directories must be real directories: ${symlinkDirConflicts.map((c) => c.path).join(", ")}`);
+        const fileConflicts = result.conflicts.filter((c) => c.reason !== "symlink-directory");
+        if (fileConflicts.length) out(`  conflicts present — pass --force to replace: ${fileConflicts.map((c) => c.path).join(", ")}`);
+      }
     }
     return 0;
   }
@@ -531,10 +596,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 });
   },
 };

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",
@@ -82,7 +83,6 @@ function installedAgentDirs(provider, cwd, env) {
 
 function sameFile(path, text) {
   try {
-    if (lstatSync(path).isSymbolicLink()) return false;
     return readFileSync(path, "utf8") === text;
   } catch {
     return false;
@@ -161,13 +161,25 @@ 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]
     .filter((path, index, all) => all.indexOf(path) === index)
-    .filter((path) => existsSync(path) && isSymlink(path))
-    .map((path) => ({ name: null, path, reason: "symlink" }));
+    .filter((path) => isSymlink(path))
+    .map((path) => ({ name: null, path, reason: "symlink-directory" }));
 
   // Plan every agent first; only touch disk once the whole set is known to be
   // conflict-free. A mixed create+conflict run must not leave a partial install.
@@ -175,29 +187,26 @@ function installProviderAgents(provider, { scope = "project", dryRun = false, fo
     const src = join(PLUGIN_ROOT, "agents", `${name}.${cfg.extension}`);
     const dest = join(dir, `${name}.${cfg.extension}`);
     const text = readFileSync(src, "utf8");
-    const exists = existsSync(dest);
-    const symlink = exists && isSymlink(dest);
+    const exists = existsSync(dest) || isSymlink(dest);
+    const staleQuestAgent = exists && !sameFile(dest, text) && existingAgentMatchesName(provider, name, dest);
     let action;
-    if (symlink) action = "conflict";
-    else if (exists && sameFile(dest, text)) action = "unchanged";
-    else if (exists && !force) action = "conflict";
+    if (exists && sameFile(dest, text)) action = "unchanged";
+    else if (exists && !force && !(replaceStale && staleQuestAgent)) action = "conflict";
     else action = exists ? "replace" : "create";
-    return { name, path: dest, action, text, reason: symlink ? "symlink" : undefined };
+    return { name, path: dest, action, text };
   });
 
   const conflicts = [
     ...dirConflicts,
-    ...plans.filter((p) => p.action === "conflict").map(({ name, path, reason }) => ({ name, path, ...(reason ? { reason } : {}) })),
+    ...plans.filter((p) => p.action === "conflict").map(({ name, path }) => ({ name, path })),
   ];
   const actions = plans.map(({ name, path, action }) => ({ name, path, action }));
   const ok = conflicts.length === 0;
 
   if (ok && !dryRun) {
-    if (dirConflicts.length) throw new Error(`refusing to write agent templates through symlinked path: ${dirConflicts.map((c) => c.path).join(", ")}`);
     for (const p of plans) {
       if (p.action === "unchanged") continue;
       mkdirSync(dir, { recursive: true });
-      if (isSymlink(dirname(p.path)) || isSymlink(p.path)) throw new Error(`refusing to write agent template through symlinked path: ${p.path}`);
       writeFileSync(p.path, p.text);
     }
   }
@@ -213,6 +222,10 @@ export function installClaudeAgents(options = {}) {
   return installProviderAgents("claude", options);
 }
 
+export function nativeProjectRoot(cwd = process.cwd(), env = process.env) {
+  return projectRoot(cwd, env);
+}
+
 function questCliPathCheck(cwd, env, versions) {
   const pathQuestVersion = runCmd("quest", ["--version"], { cwd, env });
   const pathVersion = pathQuestVersion.status === 0 ? pathQuestVersion.stdout.trim() : null;
@@ -248,7 +261,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",
@@ -423,3 +436,113 @@ export function claudeDoctor({ cwd = process.cwd(), env = process.env } = {}) {
 
   return { ok: checks.every((c) => c.ok), 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, repairs, before };
+}
+
+export function codexDoctorFix(options = {}) {
+  return doctorWithFix("codex", options);
+}
+
+export function claudeDoctorFix(options = {}) {
+  return doctorWithFix("claude", options);
+}

package/lib/help.mjs

@@ -138,30 +138,34 @@ 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, 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]",
     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"],
+      ["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"],
+      ["--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 open",
   },
   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, 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]",
     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"],
+      ["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"],
+      ["--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 open",
   },
 };
 
@@ -221,9 +225,11 @@ export function renderInitNextSteps(backend, { agentsInstalled = true } = {}) {
     "",
     "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 ? ["  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/."] : []),
   ].join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quest-loop",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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/setup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: setup
-description: Use when setting up, validating, updating, or troubleshooting Quest's native Codex or Claude plugin integration.
-argument-hint: "[doctor|install-agents|init]"
+description: Use when setting up, validating, updating, opening, or troubleshooting Quest's native Codex or Claude plugin integration.
+argument-hint: "[doctor|fix|open|install-agents|init]"
 ---
 
 # Set up Quest native agents
@@ -19,9 +19,10 @@ agent templates for both providers:
 - `.claude/agents/quest-reviewer.md`
 
 Use `quest init --no-agents` when you only want the quest store. If an existing
-project template conflicts, init fails before creating `.quests/`; inspect the
-file, run the explicit provider install command with `--force` only when you
-intend replacement, then rerun `quest init`.
+project template is stale and still identifies itself as Quest's agent, init
+replaces it. If another file conflicts, init fails before creating `.quests/`;
+inspect the file, run the explicit provider install command with `--force` only
+when you intend replacement, then rerun `quest init`.
 
 Project-scoped agent templates install at the Git repository root. For a nested
 quest store, use `quest init --no-agents` in the nested directory and set
@@ -32,7 +33,7 @@ quest store, use `quest init --no-agents` in the nested directory and set
 Check the installed Codex-facing state from the actual Codex surfaces:
 
 ```bash
-quest codex doctor
+quest codex doctor --fix
 ```
 
 This verifies the Codex CLI, `quest` binary on PATH, `multi_agent` and `goals`
@@ -45,7 +46,14 @@ use `quest-run --codex-goal-mode require` only as the headless fallback.
 Check the installed Claude-facing state from the actual Claude surfaces:
 
 ```bash
-quest claude doctor
+quest claude doctor --fix
+```
+
+Open an interactive provider only after the same repair/check gate passes:
+
+```bash
+quest codex open
+quest claude open
 ```
 
 ## Install Native Agents
@@ -70,8 +78,10 @@ quest claude install-agents --scope user
 ```
 
 If an existing file conflicts, inspect it first. Use `--force` only when you
-intend to replace that custom agent with Quest's bundled definition. Symlinked
-agent directories or files are refused rather than overwritten.
+intend to replace that custom agent with Quest's bundled definition. Stale
+Quest-owned templates are replaced without `--force`. Symlinked agent template
+files can be written through with `--force`; keep the provider agent directories
+themselves as real directories.
 
 ## Update Installed Plugin
 
@@ -81,7 +91,14 @@ refresh and reinstall, then start a new Codex thread:
 ```bash
 codex plugin marketplace upgrade quest
 codex plugin add quest@quest
-quest codex doctor
+quest codex doctor --fix
+```
+
+Claude updates through its plugin manager. After updating, restart Claude Code:
+
+```bash
+claude plugin update quest@quest
+quest claude doctor --fix
 ```
 
 If hooks changed, review/trust the updated hook definitions in Codex when