quest-loop 0.1.0 → 0.3.2

package/hooks/subagent-stop.mjs

@@ -3,12 +3,24 @@
 // recording a checkpoint — the protocol's "no stop without a checkpoint" rule,
 // enforced deterministically.
 //
-// A subagent counts as a quest-executor iff its transcript contains a
-// `quest show <id> --json` invocation (the mandatory orientation marker). We take
-// the FIRST id. No marker → 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.
+// 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
+// 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
+// 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
@@ -22,7 +34,73 @@ import { readFileSync, writeSync } from "node:fs";
 import { findStoreDir } from "../lib/config.mjs";
 import { loadQuest } from "../lib/store-local.mjs";
 
-const MARKER = /quest\s+show\s+(\d+)\s+--json/;
+// Mutating quest verbs only. Group 1 is the verb, group 2 the id. The marker is
+// anchored to a COMMAND position — an optional `node ` launcher and/or path prefix
+// then `quest <verb> <id>` at the head of a command — so `quest checkpoint 1`
+// merely quoted inside another program's argument (e.g. `grep 'quest checkpoint 1'`,
+// `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+)/;
+
+// Split a shell command into top-level segments on `&&`, `||`, `;`, `|`, and
+// newline, IGNORING any separator that sits inside single or double quotes. This
+// keeps quoted text (grep patterns, commit messages) from forging a command head.
+// (Heredoc bodies on their own line remain a rare residual; a false "checkpoint"
+// nudge is benign, and heredoc parsing is not worth the complexity in a hook.)
+function splitTopLevel(s) {
+  const segs = [];
+  let buf = "";
+  let quote = null;
+  let escaped = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (escaped) {
+      buf += c;
+      escaped = false;
+      continue;
+    }
+    if (quote !== "'" && c === "\\") {
+      buf += c;
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (c === quote) quote = null;
+      buf += c;
+      continue;
+    }
+    if (c === "'" || c === '"') { quote = c; buf += c; continue; }
+    if ((c === "&" && s[i + 1] === "&") || (c === "|" && s[i + 1] === "|")) { segs.push(buf); buf = ""; i++; continue; }
+    if (c === ";" || c === "|" || c === "\n") { segs.push(buf); buf = ""; continue; }
+    buf += c;
+  }
+  segs.push(buf);
+  return segs;
+}
+
+// Strip a leading shell wrapper (`bash -lc '…'`, `sh -c "…"`) and split the command
+// chain, then look for a quest invocation at the head of any segment. Returns the
+// marker id or null.
+function markerIdInCommand(cmd) {
+  if (typeof cmd !== "string") return null;
+  let s = cmd.trim();
+  const wrap = s.match(/^(?:sudo\s+)?(?:ba)?sh\s+-l?c\s+(['"])([\s\S]*)\1\s*$/);
+  if (wrap) s = wrap[2].trim();
+  for (const seg of splitTopLevel(s)) {
+    const m = MARKER.exec(seg.trim());
+    if (m) return Number(m[2]); // m[1] = verb, m[2] = id
+  }
+  return null;
+}
+
+// A Codex `command_execution` item's shell command, across the JSONL envelope
+// shapes we know: top-level `item`, legacy `msg` (the item sits directly at
+// `entry.msg`), and `msg.item`. Returns the command string or null.
+function commandExecutionCommand(node) {
+  if (!node || typeof node !== "object") return null;
+  if (node.type === "command_execution" && typeof node.command === "string") return node.command;
+  return null;
+}
 const TERMINAL = ["complete", "blocked", "cancelled"];
 
 async function readStdin() {
@@ -57,6 +135,59 @@ function firstTimestamp(text) {
   return null;
 }
 
+// A tool_use block's shell command, or null. Bash invocations carry the command
+// under `input.command`; only that field is a real command invocation. We never
+// scan other input fields (e.g. an Edit's new_string or a Read's file_path), which
+// could echo skill text and re-introduce the false positive.
+function commandOf(input) {
+  return input && typeof input === "object" && typeof input.command === "string" ? input.command : 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
+// ignored. Matches `quest start <id>` or `quest checkpoint <id>` and returns the id.
+function markerIdInEntry(entry) {
+  if (!entry || typeof entry !== "object") return null;
+
+  // Codex JSONL: a `command_execution` item under `item`, the legacy `msg`, or
+  // `msg.item`. Handling all three keeps executor detection robust across shapes.
+  for (const cand of [entry.item, entry.msg, entry.msg?.item]) {
+    const cmd = commandExecutionCommand(cand);
+    if (cmd != null) {
+      const id = markerIdInCommand(cmd);
+      if (id != null) return id;
+    }
+  }
+
+  // Claude assistant messages: tool_use blocks carrying a shell command. String
+  // content (plain prose) and tool_result blocks are ignored.
+  const msg = entry.message;
+  const content = msg && typeof msg === "object" ? msg.content : null;
+  if (!Array.isArray(content)) return null; // string content is prose, never an invocation
+  for (const block of content) {
+    if (!block || typeof block !== "object" || block.type !== "tool_use") continue;
+    const id = markerIdInCommand(commandOf(block.input));
+    if (id != null) return id;
+  }
+  return null;
+}
+
+// The executor's quest id = the FIRST mutating invocation (`quest start <id>` or
+// `quest checkpoint <id>`) that appears as a real command invocation, scanning
+// entries in transcript order. Returns id or null. Per-entry parsing is what keeps
+// skill-text examples from keying detection; read verbs never match at all.
+function executorQuestId(text) {
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    const id = markerIdInEntry(entry);
+    if (id != null) return id;
+  }
+  return null;
+}
+
 try {
   const raw = await readStdin();
   let payload = {};
@@ -69,9 +200,8 @@ try {
   try { transcript = readFileSync(transcriptPath, "utf8"); }
   catch (err) { diag(`cannot read transcript (${err.code || err.message}); allowing`); allow(); }
 
-  const m = MARKER.exec(transcript);
-  if (!m) allow(); // not a quest-executor subagent — leave it entirely alone, silently
-  const id = Number(m[1]);
+  const id = executorQuestId(transcript);
+  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.

package/lib/cli.mjs

@@ -11,6 +11,7 @@ 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";
 
 const PLUGIN_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -73,10 +74,96 @@ function getStore(cwd, env) {
   return loadConfig(storeDir, env);
 }
 
+function preflightInitAgentInstall(cwd, env) {
+  const plans = [
+    ["codex", installCodexAgents({ scope: "project", dryRun: true, cwd, env })],
+    ["claude", installClaudeAgents({ scope: "project", dryRun: true, cwd, env })],
+  ];
+  const conflicts = plans.flatMap(([provider, result]) => result.conflicts.map((c) => `${provider}:${c.path}`));
+  if (conflicts.length) {
+    throw new UsageError(
+      "native agent template conflict; inspect existing files or run " +
+      "`quest codex install-agents --scope project --force` / " +
+      "`quest claude install-agents --scope project --force` after resolving: " +
+      conflicts.join(", "),
+      { command: "init" },
+    );
+  }
+  return plans;
+}
+
+async function runNativeSetupCommand(command, args, { out, cwd, env }, { label, doctor, 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 });
+    if (p.help) {
+      out(renderCommandHelp(command));
+      return 0;
+    }
+    const result = 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`);
+    }
+    // 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 === "install-agents") {
+    const p = parse(command, rest, {
+      scope: { type: "string", default: "project" },
+      "dry-run": { type: "boolean" },
+      force: { type: "boolean" },
+    }, { positionals: 0 });
+    if (p.help) {
+      out(renderCommandHelp(command));
+      return 0;
+    }
+    if (!["project", "user"].includes(p.values.scope)) throw new UsageError(`--scope must be project or user (got "${p.values.scope}")`, { command });
+    const isDry = Boolean(p.values["dry-run"]);
+    const result = install({
+      scope: p.values.scope,
+      dryRun: isDry,
+      force: Boolean(p.values.force),
+      cwd,
+      env,
+    });
+    // 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 conflicts = result.conflicts.map((c) => c.path).join(", ");
+      throw new UsageError(`agent file already exists; pass --force to replace: ${conflicts}`, { command });
+    }
+    if (p.values.json) out(JSON.stringify(result));
+    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(", ")}`);
+    }
+    return 0;
+  }
+  throw new UsageError(`unknown ${command} subcommand "${subcommand}"`, { command });
+}
+
 async function dispatch(argv, ctx) {
   const [command, ...rest] = argv;
   const { out, errOut, cwd, env } = ctx;
 
+  if (command === "--version" || command === "-V" || command === "version") {
+    const versions = versionInfo();
+    out(versions.package);
+    return 0;
+  }
+
   if (!command) {
     const storeDir = findStoreDir(cwd, env);
     if (!storeDir) {
@@ -114,11 +201,16 @@ const HANDLERS = {
       backend: { type: "string", default: "local" },
       repo: { type: "string" },
       "agents-md": { type: "boolean" },
+      "no-agents": { type: "boolean" },
     });
     if (p.help) return void out(renderCommandHelp("init")) ?? 0;
     const backend = p.values.backend;
     if (!["local", "github"].includes(backend)) throw new UsageError(`--backend must be local or github (got "${backend}")`, { command: "init" });
     if (backend === "github" && !p.values.repo) throw new UsageError("--repo owner/name is required with --backend github", { command: "init" });
+    if (existsSync(join(cwd, ".quests", "config.json"))) {
+      throw new ContractError(`a quest store already exists at ${join(cwd, ".quests")}`, { hint: "use the existing store, or delete it first if you really mean to start over" });
+    }
+    const agentPlans = p.values["no-agents"] ? [] : preflightInitAgentInstall(cwd, env);
     if (backend === "github") {
       github.assertAuth(env); // green `gh auth status` required
       github.ensureLabels(p.values.repo, env); // idempotent label creation
@@ -127,7 +219,7 @@ const HANDLERS = {
     const config = {
       backend,
       ...(p.values.repo ? { github: { repo: p.values.repo } } : {}),
-      defaults: { worker: "claude", claude: { model: "opus", effort: "xhigh" }, codex: { model: "gpt-5.5", reasoning_effort: "medium" }, max_iterations: 8, priority: "p2" },
+      defaults: { worker: "claude", claude: { model: "opus", effort: "xhigh" }, codex: { model: "gpt-5.5", reasoning_effort: "medium", goal_mode: "auto" }, max_iterations: 8, priority: "p2" },
       notify: { command: "" },
     };
     writeFileSync(join(storeDir, "config.json"), JSON.stringify(config, null, 2) + "\n");
@@ -145,8 +237,15 @@ const HANDLERS = {
       ].join("\n");
       appendFileSync(join(cwd, "AGENTS.md"), section);
     }
+    for (const [provider] of agentPlans) {
+      const label = provider === "codex" ? "Codex" : "Claude";
+      const install = provider === "codex" ? installCodexAgents : installClaudeAgents;
+      const result = install({ scope: "project", cwd, env });
+      out(`Installed ${label} agents to ${result.target}`);
+      for (const a of result.actions) out(`  ${a.action.padEnd(9)} ${a.path}`);
+    }
     out(`Initialized ${backend} quest store at ${storeDir}`);
-    out(renderInitNextSteps(backend));
+    out(renderInitNextSteps(backend, { agentsInstalled: agentPlans.length > 0 }));
     return 0;
   },
 
@@ -309,6 +408,38 @@ const HANDLERS = {
     return 0;
   },
 
+  async reopen(args, { out, errOut, cwd, env }) {
+    const p = parse("reopen", args, { reason: { type: "string" } }, { positionals: 1 });
+    if (p.help) return void out(renderCommandHelp("reopen")) ?? 0;
+    const id = requireId(p, "reopen");
+    // --reason is validated in the store (a contract requirement, exit 5), not
+    // as a usage error — mirrors `cancel`. reopenQuest throws if it is missing.
+    const config = getStore(cwd, env);
+    const store = openStore(config, { env });
+    const q = store.reopenQuest(id, p.values.reason);
+    // Reopening a child of a *complete* parent epic is allowed, never blocked —
+    // but the epic's completion verdict may now be falsified, so warn the
+    // orchestrator on stderr (the epic-falsification cue). Best-effort: a
+    // missing/unloadable parent (or any lookup failure) must never fail an
+    // already-successful reopen. Runs for both backends via this one handler.
+    if (q.front.parent !== undefined) {
+      try {
+        const parent = store.loadQuest(q.front.parent);
+        if (parent.front.status === "complete") {
+          errOut(`quest: warning — quest ${id}'s parent epic ${q.front.parent} is complete; reopening this child may falsify the epic's completion verdict. Rule on it, and \`quest reopen ${q.front.parent} --reason "…"\` too if the integration gate no longer holds.`);
+        }
+      } catch {
+        /* best-effort: never fail the reopen on a parent-lookup problem */
+      }
+    }
+    if (p.values.json) out(JSON.stringify({ ok: true, id, status: q.front.status }));
+    else {
+      out(`Quest ${id} reopened — now in_progress (reason recorded in an audited checkpoint).`);
+      out(`Reopened quests are dispatched directly by id (\`quest-run ${id}\` or $quest:work ${id}); they do not re-enter \`quest list --ready\`.`);
+    }
+    return 0;
+  },
+
   async edit(args, { out, cwd, env }) {
     const p = parse("edit", args, {
       "add-done-when": { type: "string", multiple: true },
@@ -398,4 +529,12 @@ const HANDLERS = {
     else for (const r of runs) out(`${r.run_id}  quest ${r.quest}  ${r.worker}  ${r.ended ? `ended ${r.final_status}` : "ACTIVE"}  iters:${r.iterations}  $${r.cost_usd.toFixed(2)}`);
     return 0;
   },
+
+  async codex(args, { out, cwd, env }) {
+    return runNativeSetupCommand("codex", args, { out, cwd, env }, { label: "Codex", doctor: codexDoctor, install: installCodexAgents });
+  },
+
+  async claude(args, { out, cwd, env }) {
+    return runNativeSetupCommand("claude", args, { out, cwd, env }, { label: "Claude", doctor: claudeDoctor, install: installClaudeAgents });
+  },
 };