quest-loop 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+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/).
+
+## [0.1.0] — 2026-07-07
+
+First public release. The build of this release was itself executed as quests
+1–12 in [`.quests/`](./.quests/) — contracts, checkpoints, an adversarial
+review round, and a retro with five protocol amendments.
+
+### Added
+- `quest` CLI — the quest store: contracts with Objective / Done-when /
+  Validation-loop anchors, evidence-citing checkpoints, wave scheduling
+  (`list --ready`), compatible-expansion edits, lint, protocol + amendments.
+  Zero dependencies; strict fail-honest parsing; guided help on every command.
+- Two store backends: local markdown (default) and GitHub Issues via `gh`
+  (labels mirror status/priority, checkpoints are issue comments, identical
+  bytes across backends).
+- `quest-run` — headless runner driving **Claude** (`claude -p`, native `/goal`
+  mode) and **Codex** (`codex exec`, goal-tools prompt + corrective/continuation
+  resume) workers; deterministic budgets (sessions, cost, tokens), wall-clock
+  session timeout, stall enforcement, runs journal, `--notify`, `--parallel`
+  with optional worktree isolation, configurable codex sandbox mode.
+- Five skills (`/quest:plan`, `/quest:work`, `/quest:orchestrate`,
+  `/quest:retro`, `/quest:protocol`) and two agents (`quest-executor`,
+  `quest-reviewer`), served to both harnesses from one tree.
+- Hooks: SessionStart in-flight summary; SubagentStop checkpoint enforcement.
+- CI: tests (Node 20/24), hygiene, manifest validation, agent/skill parity,
+  gitleaks secret scan.
+- Repository scaffold: dual plugin manifests (Claude Code + Codex), protocol
+  and record-format specifications, bootstrap quest store tracking this
+  project's own build.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Sreberski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# quest
+
+Goal-loop engineering for coding agents — one plugin for **Claude Code** and
+**Codex**, plus a zero-dependency CLI.
+
+quest turns asks into **evidence-checkable contracts** ("quests"), executes them
+in **iterative loops that end in verifiable checkpoints**, orchestrates **Claude
+and Codex workers** (in-session or headless, serial or parallel), and mines
+retrospectives into **numbered protocol amendments** your future sessions
+actually read.
+
+- `quest` — the quest store: contracts, checkpoints, wave scheduling. Local
+  markdown files by default; GitHub Issues opt-in.
+- `quest-run` — the headless runner: drives `claude -p` or `codex exec` workers
+  in native goal mode with deterministic budgets and notifications.
+- Five skills — `/quest:plan`, `/quest:work`, `/quest:orchestrate`,
+  `/quest:retro`, `/quest:protocol`.
+- Two agents — `quest-executor`, `quest-reviewer`.
+
+## The idea in 30 seconds
+
+```
+you:    /quest:plan add dark mode to the settings page
+agent:  creates quest 12 — Objective, Done-when, Validation loop… (quest create)
+you:    /quest:orchestrate
+agent:  dispatches a worker on quest 12; it iterates: milestone → validate →
+        commit → checkpoint. You review evidence, not vibes.
+```
+
+Every quest ends in a checkpoint trail a fresh session can resume from — that is
+the whole trick.
+
+## Install
+
+### CLI (any environment)
+
+```bash
+npm install -g quest-loop
+```
+
+Puts `quest` and `quest-run` on your PATH everywhere — no harness required.
+The plugin installs below add the skills, agents, and hooks on top.
+
+### Claude Code
+
+```bash
+claude plugin marketplace add robertsreberski/quest
+```
+
+Then, inside a Claude Code session:
+
+```
+/plugin install quest@quest
+```
+
+For local development against a checkout, point Claude Code at the repo directly
+— no marketplace needed:
+
+```bash
+claude --plugin-dir .
+```
+
+### Codex
+
+The plugin ships a `.codex-plugin/` manifest and discovers its skills from the
+repo checkout (`skills/`, surfaced under `.agents/` for Codex). Until a public
+Codex marketplace listing is approved upstream, wire it up from a clone or
+submodule:
+
+```bash
+git clone https://github.com/robertsreberski/quest
+# add the checkout to your Codex plugin/skill discovery path (clone or submodule)
+```
+
+The CLI (`quest`, `quest-run`) is harness-agnostic — it works the same whether
+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:
+
+```bash
+# 1. Create a quest store (.quests/) here
+quest init
+
+# 2. Author a quest — the CLI is the only way records are born
+quest create --title "Add dark mode" \
+  --objective "Settings page offers a dark theme that persists." \
+  --done-when "toggling theme updates the UI and survives reload" \
+  --done-when "\`npm test\` passes including new theme tests" \
+  --validation "npm test"
+
+# 3. Check it against the contract spec
+quest lint --all
+
+# 4. See what's ready to work (dependencies met)
+quest list --ready
+```
+
+Work the quest **in-session** with the skill:
+
+```
+/quest:work 12
+```
+
+…or **headless** with the runner:
+
+```bash
+quest-run 12
+```
+
+Each iteration ends by recording evidence — a checkpoint a fresh session can
+resume from:
+
+```bash
+quest checkpoint 12 --status complete \
+  --summary "M2 done — theme persistence via localStorage" \
+  --validation "\`npm test\` → 42 passed, 0 failed"
+```
+
+Run `quest <command> --help` for flags and a copy-pasteable example of any
+command.
+
+## The loop
+
+A quest is a goal contract: one Objective, evidence-checkable *Done-when*
+conditions, a Validation loop of exact commands, and optional milestones. Each
+iteration picks the smallest unfinished milestone, implements it end-to-end,
+runs the Validation loop **exactly as written**, commits green, and records a
+checkpoint citing the commands it ran and what they returned. A quest is
+`complete` only when every Done-when item is enumerated with its evidence. The
+full base protocol lives in
+[`skills/protocol/references/protocol.md`](./skills/protocol/references/protocol.md)
+(print it, with this store's local amendments, via `quest protocol`).
+
+## CLI overview
+
+| Command | Purpose |
+|---|---|
+| `quest init` | Create a quest store (`.quests/`) in the current directory |
+| `quest create` | Create a new quest (the only way records are born) |
+| `quest list` | List quests (filter by status, parent, or readiness) |
+| `quest show` | Show a quest record in full |
+| `quest start` | Mark a quest in_progress (todo → in_progress) |
+| `quest checkpoint` | Record iteration evidence and drive the quest's status |
+| `quest cancel` | Cancel a quest (terminal; reason is recorded) |
+| `quest edit` | Compatibly expand a quest (additions only; anchors are immutable) |
+| `quest lint` | Check records against the contract spec |
+| `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-run (headless runner)
+
+`quest-run <id>` drives a worker through the same loop without you in the chair:
+
+- **Workers** — `claude` (`claude -p`) or `codex` (`codex exec`), selected per
+  quest. Both run in **native goal mode** with a machine-verifiable completion
+  condition.
+- **Budgets** — deterministic iteration, cost, token, and per-session
+  wall-clock (`--session-timeout`, default 1800s) caps; two sessions without a
+  new checkpoint (a killed hung session counts as one) auto-writes a `blocked`
+  checkpoint and stops.
+- **Backends** — drives `local` and `github`-backed stores alike; all record IO
+  goes through the `quest` CLI, and the runs journal stays local.
+- **`--parallel N`** — with `--ready`, promotes and works newly-ready quests
+  across dependency waves, up to N at a time.
+- **`--notify '<cmd>'`** — runs a templated command on run start/stop so you get
+  pinged; notify failures are isolated from the run.
+- **`--codex-sandbox <mode>`** — selects the `codex exec` sandbox
+  (`read-only` | `workspace-write` | `danger-full-access`; resolved as flag →
+  config `defaults.codex.sandbox` → default `workspace-write`). Honest tradeoff:
+  the default **`workspace-write` write-protects `.git`, so a codex worker cannot
+  `git commit` under it** (the `index.lock` write fails). A quest whose worker
+  must commit has to opt into **`danger-full-access`** — which also grants full
+  disk and network access. The runner never escalates the sandbox silently; the
+  safe `workspace-write` stays the default. (Claude workers ignore this flag.)
+
+Inspect activity with `quest runs --active`.
+
+> **Note:** `quest-run` ships with this build's runner milestone (tracked as
+> quest 5). On a pre-0.1.0 checkout where `bin/quest-run` isn't present yet, use
+> `/quest:work` in-session instead.
+
+## Store backends
+
+- **`local`** (default) — records are markdown files under `.quests/quests/`;
+  config, amendments, and the runs journal stay local. Zero dependencies.
+- **`github`** (opt-in) — `quest init --backend github --repo owner/name` stores
+  records as GitHub Issues via the `gh` CLI (labels mirror status/priority;
+  checkpoints become issue comments). Config, amendments, and runs stay local.
+
+```bash
+quest init --backend github --repo owner/name
+```
+
+The GitHub backend (`quest init --backend github`) and the headless runner
+(`quest-run`) work together — `quest-run <id>` drives quests in a github-backed
+store exactly as it does locally.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 2 | usage error (bad flags/arguments) |
+| 3 | no quest store found / config invalid |
+| 4 | quest not found |
+| 5 | contract violation (lint failure, malformed record, illegal transition) |
+| 6 | backend unavailable (`gh` missing, unauthenticated, network) |
+| 10 | (`quest-run`) ended blocked |
+| 11 | (`quest-run`) budget exhausted |
+
+## Status
+
+The build of quest is itself tracked as quests — see [`.quests/`](./.quests/).
+Contributions welcome; see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT

package/agents/quest-executor.md

@@ -0,0 +1,42 @@
+---
+name: quest-executor
+description: Works exactly one quest record iteratively per the quest protocol until complete or blocked, recording checkpoint evidence via the quest CLI. Dispatch with the quest id; pass the record's model/effort as the dispatch override. <example>Orchestrator sees quest 12 ready with worker claude → dispatches quest-executor with "Work quest 12 per /quest:work"; it iterates milestone-by-milestone and ends with a recorded checkpoint.</example> <example>A quest sits blocked after a human ruling → redispatch quest-executor with the ruling; it resumes from the checkpoint trail alone.</example>
+model: opus
+effort: xhigh
+tools: Bash, Read, Edit, Write, Glob, Grep, WebFetch, WebSearch, NotebookEdit
+---
+
+You execute ONE quest. Decomposition, dispatching, and rulings belong to the
+orchestrator — which is why you have no agent-spawning tools. Your work exists
+only insofar as it is recorded in the quest's checkpoint trail.
+
+## First actions, always
+
+```bash
+quest show <id> --json    # the contract and every prior checkpoint
+quest protocol            # the loop rules + this store's amendments
+git log --oneline -5
+```
+
+Then follow the work skill (`/quest:work`) exactly: smallest unfinished
+milestone → the quest's STATED validation loop → commit green → `quest
+checkpoint`. The record is your entire spec; if you need context it doesn't
+give you, read the code it points at — and if it's genuinely insufficient,
+checkpoint `blocked` saying exactly what's missing.
+
+## Non-negotiable backstops
+
+- Never stop — for any reason — without recording a checkpoint via
+  `quest checkpoint`. A stop without one is a protocol violation.
+- Never edit or delete existing tests to make them pass.
+- Never fake success or hide a failure behind a fallback; report the real state.
+- Never substitute a stated validation check silently — name any substitution.
+- An unsatisfiable Done-when, the same error twice, or a human-only decision →
+  `--status blocked` with the exact discrepancy. Blocked beats improvised.
+- Respect `max_iterations`; if exhausted, checkpoint blocked with the reason.
+
+## Final report
+
+End with `quest show <id>` so the recorded state is visible, then report
+exactly three things: the quest_status you recorded, the checkpoint timestamp,
+and a one-line evidence summary citing the decisive command + result.

package/agents/quest-executor.toml

@@ -0,0 +1,27 @@
+name = "quest-executor"
+description = "Works exactly one quest record iteratively per the quest protocol until complete or blocked, recording checkpoint evidence via the quest CLI."
+model_reasoning_effort = "high"
+developer_instructions = """
+You execute ONE quest. Decomposition, dispatching, and rulings belong to the
+orchestrator. Your work exists only insofar as it is recorded in the quest's
+checkpoint trail.
+
+First actions, always: `quest show <id> --json`, `quest protocol`,
+`git log --oneline -5`. Then follow the work skill exactly: smallest unfinished
+milestone -> the quest's STATED validation loop -> commit green ->
+`quest checkpoint`. The record is your entire spec; if it is genuinely
+insufficient, checkpoint blocked saying exactly what is missing.
+
+Non-negotiable backstops:
+- Never stop without recording a checkpoint via `quest checkpoint`.
+- Never edit or delete existing tests to make them pass.
+- Never fake success or hide a failure behind a fallback.
+- Never substitute a stated validation check silently — name any substitution.
+- Unsatisfiable Done-when, same error twice, or a human-only decision ->
+  --status blocked with the exact discrepancy. Blocked beats improvised.
+- Respect max_iterations; if exhausted, checkpoint blocked with the reason.
+
+Final report: run `quest show <id>` so recorded state is visible, then report
+the quest_status you recorded, the checkpoint timestamp, and a one-line
+evidence summary citing the decisive command + result.
+"""

package/agents/quest-reviewer.md

@@ -0,0 +1,32 @@
+---
+name: quest-reviewer
+description: Adversarial reviewer for quests claiming complete — verifies the checkpoint evidence actually discharges every Done-when item and hunts silent substitutions, fake greens, and scope drift. Dispatch before accepting any non-trivial complete ruling. <example>Executor checkpoints quest 12 complete → orchestrator dispatches quest-reviewer on the diff + record; it re-runs the validation loop and reports findings with required dispositions.</example>
+model: opus
+effort: xhigh
+tools: Bash, Read, Glob, Grep
+---
+
+You verify, adversarially, that a quest claiming `complete` earned it. You do
+not fix anything — you report findings the orchestrator must disposition.
+
+## Procedure
+
+1. Read the contract and trail: `quest show <id> --json`, `quest protocol`.
+2. Read the ACTUAL changes (diff/commits the checkpoints cite), not the
+   summary of them.
+3. Re-run the quest's stated Validation loop yourself. The checkpoint's claims
+   must reproduce; "it said so" is not evidence.
+4. Interrogate each Done-when item: which command output proves it? Was a
+   stated check substituted without being named? Did tests get edited to pass?
+   Did scope drift past the Objective without a recorded expansion?
+5. Check the trail itself: could a zero-context session resume this quest from
+   the record alone? Are references symbol+file (not rotted line numbers)?
+
+## Report
+
+Findings ordered by severity, each with: what's wrong, the evidence (command +
+output or file + symbol), and why it blocks acceptance. If nothing survived
+your scrutiny, say "no findings" plainly — do not invent nitpicks. End with a
+verdict: **accept** / **iterate** (list exactly what must change) — the
+orchestrator rules; every finding you raise must receive a disposition
+(fixed / follow-up quest / rejected-with-reason) before the quest is accepted.

package/agents/quest-reviewer.toml

@@ -0,0 +1,21 @@
+name = "quest-reviewer"
+description = "Adversarial reviewer for quests claiming complete — verifies the checkpoint evidence actually discharges every Done-when item and hunts silent substitutions, fake greens, and scope drift."
+model_reasoning_effort = "high"
+developer_instructions = """
+You verify, adversarially, that a quest claiming complete earned it. You do not
+fix anything — you report findings the orchestrator must disposition.
+
+Procedure: read the contract and trail (`quest show <id> --json`,
+`quest protocol`); read the ACTUAL changes the checkpoints cite, not the
+summary; re-run the quest's stated Validation loop yourself — claims must
+reproduce; interrogate each Done-when item (which command output proves it?
+was a stated check substituted silently? were tests edited to pass? did scope
+drift past the Objective without a recorded expansion?); check the trail
+itself (could a zero-context session resume from the record alone?).
+
+Report findings ordered by severity, each with the evidence (command + output
+or file + symbol) and why it blocks acceptance. If nothing survived scrutiny,
+say "no findings" plainly — do not invent nitpicks. End with a verdict:
+accept, or iterate with exactly what must change. Every finding must receive a
+disposition (fixed / follow-up quest / rejected-with-reason) before acceptance.
+"""

package/bin/quest

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "../lib/cli.mjs";
+process.exit(await run(process.argv.slice(2)));

package/bin/quest-run

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "../lib/runner.mjs";
+process.exit(await run(process.argv.slice(2)));

package/hooks/hooks.json

@@ -0,0 +1,32 @@
+{
+  "description": "Quest goal-loop hooks: inject in-flight quest context at session start, and block quest-executor subagents that try to stop without recording a checkpoint.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"" }
+        ]
+      },
+      {
+        "matcher": "clear",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"" }
+        ]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"" }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-stop.mjs\"" }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-start.mjs

@@ -0,0 +1,61 @@
+#!/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.
+
+import { writeSync } from "node:fs";
+import { findStoreDir, loadConfig } from "../lib/config.mjs";
+import { listQuests, readRuns } from "../lib/store-local.mjs";
+
+const STATUS_ORDER = ["in_progress", "blocked", "todo", "complete", "cancelled"];
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function activeRunCount(storeDir) {
+  const runs = readRuns(storeDir);
+  const ended = new Set(runs.filter((r) => r.event === "run_ended").map((r) => r.run_id));
+  return runs.filter((r) => r.event === "run_started" && !ended.has(r.run_id)).length;
+}
+
+// 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).
+function buildContext(storeDir) {
+  const all = listQuests(storeDir);
+  if (!all.length) return null;
+  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
+    .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}]`);
+  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\`.`);
+  return lines.join("\n");
+}
+
+try {
+  const raw = await readStdin();
+  let payload = {};
+  try { payload = raw.trim() ? JSON.parse(raw) : {}; } catch { payload = {}; }
+  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 context = buildContext(storeDir);
+  if (context) writeSync(1, context + "\n");
+  process.exit(0);
+} catch (err) {
+  // Never turn a best-effort context hint into a session error.
+  writeSync(2, `quest session-start hook: ${err.message}\n`);
+  process.exit(0);
+}

package/hooks/subagent-stop.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// SubagentStop hook. Blocks a quest-executor subagent that tries to stop without
+// 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.
+//
+// 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.
+//
+// Block contract (Claude Code command hook): print {"decision":"block","reason"}
+// to stdout and exit 0. (Note: the {"ok":false,...} shape is for prompt/agent
+// hooks, not command hooks — see the checkpoint notes for this quest.)
+
+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/;
+const TERMINAL = ["complete", "blocked", "cancelled"];
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function allow() { process.exit(0); }
+function diag(msg) { writeSync(2, `quest subagent-stop hook: ${msg}\n`); }
+function block(id) {
+  const reason = `quest ${id}: record a checkpoint via \`quest checkpoint ${id}\` before stopping (protocol: no stop without a checkpoint)`;
+  writeSync(1, JSON.stringify({ decision: "block", reason }) + "\n");
+  process.exit(0);
+}
+
+function toMs(v) {
+  if (typeof v !== "string" || !v) return null;
+  const ms = Date.parse(v);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+// The subagent's start = the first parseable `timestamp` in the JSONL transcript.
+function firstTimestamp(text) {
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    const ms = obj && typeof obj === "object" ? toMs(obj.timestamp) : null;
+    if (ms != null) return ms;
+  }
+  return null;
+}
+
+try {
+  const raw = await readStdin();
+  let payload = {};
+  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(); }
+
+  let transcript;
+  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]);
+
+  // 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(); }
+
+  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(); }
+
+  let quest;
+  try { quest = loadQuest(storeDir, id); }
+  catch (err) { diag(`quest ${id}: ${err.message}; allowing`); allow(); }
+
+  // A checkpoint recorded after the subagent started clears the stop.
+  const latestCp = quest.checkpoints.reduce((max, cp) => {
+    const ms = toMs(cp.timestamp);
+    return ms != null && ms > max ? ms : max;
+  }, -Infinity);
+  if (latestCp > start) allow();
+
+  // A terminal store status reached during this run also clears it — covers
+  // `quest cancel`, which records a note rather than a checkpoint marker.
+  const updated = toMs(quest.front.updated);
+  if (TERMINAL.includes(quest.front.status) && updated != null && updated > start) allow();
+
+  block(id);
+} catch (err) {
+  diag(err.message);
+  process.exit(0);
+}