@bojackduy/opencode-learn 1.2.4 → 1.3.0

package/README.md

@@ -115,6 +115,8 @@ quiz_batch(quizzes=[{question:"…", options:[…], correctAnswer:["Red","Blue"]
 ```
 Single → TUI popup `QuizDialog` (single/multi + `I don't know` + note). Batch → deck `1/3→3/3` `QuizBatchDialog` (same 4-state `hit/miss/false-alarm/correct-rejection` solid `bg` inverted). Both durable `pendingDir` `.opencode/learn-pending` — kill `opencode` mid-popup → re-show on restart.
 
+Quiz dialogs are asynchronous. The agent must call `quiz` or `quiz_batch` alone, end that assistant turn once the dialog is displayed, and continue only after the TUI injects the learner's answer.
+
 Open forks: native `question` (single/multi `Other`).
 
 **Visual — one correct picture**

package/dist/server.js

@@ -529,24 +529,31 @@ function watchAndInject(client, directory, id, sessionID, buildText) {
     slog("watchAndInject no sessionID", id);
     return;
   }
+  activeWatchers.get(id)?.();
   const dir = pendingDir(directory);
   const respPath = path.join(dir, `response-${id}.json`);
   const claimPath = path.join(dir, `response-${id}.claim-${process.pid}.json`);
   const pendingCandidates = [path.join(dir, `quiz-${id}.json`), path.join(dir, `quiz_batch-${id}.json`)];
+  let watcher;
+  let pollTimer;
+  let closed = false;
   const closeWatcher = () => {
-    const w = activeWatchers.get(id);
-    if (w) {
-      try {
-        w.close();
-      } catch {}
+    if (closed)
+      return;
+    closed = true;
+    try {
+      watcher?.close();
+    } catch {}
+    if (pollTimer)
+      clearInterval(pollTimer);
+    if (activeWatchers.get(id) === closeWatcher)
       activeWatchers.delete(id);
-    }
   };
+  activeWatchers.set(id, closeWatcher);
   const fire = async (attempt = 0) => {
     try {
       fs.renameSync(respPath, claimPath);
     } catch {
-      closeWatcher();
       return;
     }
     let data;
@@ -626,13 +633,17 @@ function watchAndInject(client, directory, id, sessionID, buildText) {
     }
     if (!ok) {
       slog("watchAndInject inject FAILED, preserved", id, effectiveSessionID, String(firstErr).slice(0, 200));
+      closeWatcher();
       try {
-        fs.renameSync(claimPath, path.join(dir, `response-${id}.failed-${Date.now()}.json`));
-      } catch {}
+        fs.renameSync(claimPath, respPath);
+      } catch {
+        try {
+          fs.renameSync(claimPath, path.join(dir, `response-${id}.failed-${Date.now()}.json`));
+        } catch {}
+      }
       try {
         await client.app.log({ body: { service: "learn", level: "error", message: `inject FAILED for ${effectiveSessionID} (orig ${sessionID})`, extra: { id } } });
       } catch {}
-      closeWatcher();
       return;
     }
     try {
@@ -649,13 +660,19 @@ function watchAndInject(client, directory, id, sessionID, buildText) {
     } catch {}
   };
   try {
-    const w = fs.watch(dir, (_e, filename) => {
-      if (filename === `response-${id}.json`)
-        fire();
+    watcher = fs.watch(dir, () => {
+      fire();
     });
-    w.on("error", () => {});
-    activeWatchers.set(id, w);
+    watcher.on("error", () => {});
   } catch {}
+  pollTimer = setInterval(() => {
+    if (fs.existsSync(respPath)) {
+      fire();
+      return;
+    }
+    if (!pendingCandidates.some((p) => fs.existsSync(p)) && !fs.existsSync(claimPath))
+      closeWatcher();
+  }, 500);
   if (fs.existsSync(respPath)) {
     slog("watchAndInject fast-path", id);
     fire();
@@ -901,16 +918,16 @@ Return ONLY JSON: {"inferred":[2],"semanticCorrect":false,"reason":"...","isIDK"
         slog("classify response written", data.id, inferred.join(","));
       } catch {}
     };
+    const sweep = () => {
+      try {
+        for (const f of fs.readdirSync(dir).filter((f) => f.startsWith("classify-") && !f.startsWith("classify-response-"))) {
+          processClassify(f);
+        }
+      } catch {}
+    };
+    sweep();
     try {
-      for (const f of fs.readdirSync(dir).filter((f) => f.startsWith("classify-") && !f.startsWith("classify-response-"))) {
-        processClassify(f);
-      }
-    } catch {}
-    try {
-      const w = fs.watch(dir, (_e, filename) => {
-        if (filename)
-          processClassify(filename);
-      });
+      const w = fs.watch(dir, () => sweep());
       w.on("error", () => {});
     } catch {}
   }
@@ -1165,9 +1182,9 @@ Explanation: ${j.explanation}${note}`;
     },
     tool: {
       quiz: tool({
-        description: "Ask the user a GRADED question with a known correct answer, then grade and give feedback. Unlike the native `question` tool (which collects preferences with no right answer), `quiz` has a correct answer, marks selection right/wrong, reveals correct answer, and shows explanation. Use to assess understanding before teaching and for retrieval practice after. Options-only: single/multi-select plus auto 'I don't know'. No free-text. For non-graded questions use the native `question` tool.",
+        description: "Ask the user a GRADED question with a known correct answer, then grade and give feedback. Unlike the native `question` tool (which collects preferences with no right answer), `quiz` has a correct answer, marks selection right/wrong, reveals the correct answer, and shows an explanation. The TUI interaction is asynchronous, so call `quiz` ALONE in an assistant turn: never call it in parallel or in the same response with native `question`, another `quiz`, `quiz_batch`, or any other user-input tool. When the result says displayed/waiting, end the turn immediately; the answer will be injected as a new turn. Only call native `question` after `quiz` if its result explicitly requests the no-TUI fallback. Use to assess understanding before teaching and for retrieval practice after. Options-only: single/multi-select plus auto 'I don't know'. No free-text. For non-graded questions use the native `question` tool.",
         args: {
-          question: tool.schema.string().describe("Single quiz question to ask. One per call."),
+          question: tool.schema.string().describe("Single quiz question to ask. Call this tool alone; do not combine it with another user-input tool in the same turn."),
           details: tool.schema.string().optional().describe("Extra context shown under question."),
           options: tool.schema.array(tool.schema.object({
             label: tool.schema.string().describe("Display label"),
@@ -1265,7 +1282,7 @@ Explanation: ${eFixed}${note}`;
             }
           }
           if (tuiAlive) {
-            return `[quiz displayed in TUI \u2014 waiting for your answer in the popup. I'll continue once you respond.]`;
+            return `[quiz displayed in TUI - waiting for the user's answer in the popup. STOP this assistant turn now. Do not call \`question\`, another tool, or ask another question in text. The answer will be injected as a new turn.]`;
           }
           const isTTY = process.stdin?.isTTY && process.stdout?.isTTY;
           const insideOpencode = !!process.env?.OPENCODE || !!process.env?.OPENCODE_TUI;
@@ -1344,7 +1361,7 @@ Explanation: ${eFixed}`;
         }
       }),
       quiz_batch: tool({
-        description: "Batch version of quiz \u2014 shows 2-8 graded questions as a deck (Quiz 1/3 \u2192 2/3 \u2192 3/3) in one beautiful TUI, then one combined inject. Use when you want multiple probes without separate tool calls. Each entry has same schema as quiz.",
+        description: "Batch version of quiz - shows 2-8 graded questions as a deck (Quiz 1/3 to 2/3 to 3/3) in one TUI, then injects one combined answer. The TUI interaction is asynchronous, so call `quiz_batch` ALONE in an assistant turn: never call it in parallel or in the same response with native `question`, `quiz`, another `quiz_batch`, or any other user-input tool. When the result says displayed/waiting, end the turn immediately; the answers will be injected as a new turn. Use when you want multiple non-adaptive checks in one deck. Each entry has the same schema as quiz.",
         args: {
           quizzes: tool.schema.array(tool.schema.object({
             question: tool.schema.string(),
@@ -1454,9 +1471,9 @@ Explanation: ${eFixed}`;
           });
           slog("quiz_batch watchAndInject armed", id, "alive", isAlive);
           if (isAlive)
-            return `[quiz batch displayed in TUI \u2014 ${normalized.length} quizzes as deck Quiz 1/${normalized.length} \u2192 ${normalized.length}/${normalized.length}. Answer all, then one combined inject.]`;
+            return `[quiz batch displayed in TUI - ${normalized.length} quizzes as deck Quiz 1/${normalized.length} to ${normalized.length}/${normalized.length}. STOP this assistant turn now. Do not call \`question\`, another tool, or ask another question in text. The answers will be injected as a new turn.]`;
           else
-            return `[quiz batch displayed durably \u2014 TUI not alive yet, will appear on restart. Answer all, then one combined inject.]`;
+            return `[quiz batch stored durably - TUI not alive yet, so it will appear on restart. STOP this assistant turn now. Do not call \`question\`, another tool, or ask another question in text. The answers will be injected after the user completes the deck.]`;
         }
       }),
       md_log: tool({

package/dist/tui.js

@@ -2628,6 +2628,14 @@ var tui = async (api) => {
     } catch {}
     return null;
   };
+  const hasAnswerArtifact = (id) => {
+    const response = `response-${id}`;
+    try {
+      return fs.readdirSync(pendingDir).some((file) => file === `${response}.json` || file.startsWith(`${response}.claim-`));
+    } catch {
+      return false;
+    }
+  };
   const processPending = () => {
     const curSid = getCurrentSessionID();
     if (!curSid)
@@ -2653,13 +2661,7 @@ var tui = async (api) => {
       } catch {
         return null;
       }
-    }).filter(Boolean).filter((x) => {
-      try {
-        return !fs.existsSync(path.join(pendingDir, `response-${x.j.id}.json`));
-      } catch {
-        return true;
-      }
-    });
+    }).filter(Boolean).filter((x) => !hasAnswerArtifact(x.j.id));
     const pick = matching.find((x) => x.j.sessionID === curSid) || matching.find((x) => !x.j.sessionID);
     if (!pick)
       return;

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@bojackduy/opencode-learn",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "Pi learn system for OpenCode — Socratic teaching, graded quiz, Obsidian md_log, and visual makers. Port of amosblomqvist/learn (video: How I Use AI to Learn Things) to OpenCode.",
   "type": "module",
   "license": "AGPL-3.0-or-later",

package/plugins/learn-tui.tsx

@@ -778,6 +778,15 @@ export const tui: TuiPlugin = async (api) => {
     return null
   }
 
+  const hasAnswerArtifact = (id: string): boolean => {
+    const response = `response-${id}`
+    try {
+      return fs.readdirSync(pendingDir).some((file) => file === `${response}.json` || file.startsWith(`${response}.claim-`))
+    } catch {
+      return false
+    }
+  }
+
   const processPending = () => {
     const curSid = getCurrentSessionID()
     if (!curSid) return
@@ -788,9 +797,7 @@ export const tui: TuiPlugin = async (api) => {
     try { files = fs.readdirSync(pendingDir).filter(f => f.endsWith(".json") && !f.startsWith("response-") && !f.startsWith(".") && !f.startsWith("classify")).sort() } catch { return }
     // Session-distinct: only show pending for current session.
     // Skip answered-pending (a response file exists, server is consuming): prevents re-popup after answer.
-    const matching = files.map(f => { try { const j = JSON.parse(fs.readFileSync(path.join(pendingDir, f), "utf8")) as any; return { f, j } } catch { return null } }).filter(Boolean).filter(x => {
-      try { return !fs.existsSync(path.join(pendingDir, `response-${x!.j.id}.json`)) } catch { return true }
-    }) as Array<{f: string, j: any}>
+    const matching = files.map(f => { try { const j = JSON.parse(fs.readFileSync(path.join(pendingDir, f), "utf8")) as any; return { f, j } } catch { return null } }).filter(Boolean).filter(x => !hasAnswerArtifact(x!.j.id)) as Array<{f: string, j: any}>
     const pick = matching.find(x => x.j.sessionID === curSid) || matching.find(x => !x.j.sessionID)
     if (!pick) return
     const file = pick.f
@@ -875,12 +882,12 @@ export const tui: TuiPlugin = async (api) => {
           }
         }
       } catch {}
-      // Server owns lifecycle: it unlinks the pending file after successful inject.
-      // Do NOT delete pending here — deleting it destroys recovery context if the server hasn't consumed the response yet.
+      // Keep the pending payload until the server confirms injection. It is the recovery context
+      // needed to rebuild the prompt if either process exits after the answer is written.
       api.ui.dialog.clear()
       currentBySession.delete(curSid)
       setTimeout(processPending, 150)
-      // Watchdog: if the response is still unconsumed after 8s, re-touch to retrigger the server watch + log loudly.
+      // Watchdog: if the response is still unconsumed (server didn't fire) after 8s, re-touch to retrigger the watch + log loudly.
       // Safe: server claims via atomic rename, so a rewrite can never cause double-inject.
       setTimeout(() => {
         try {
@@ -910,7 +917,7 @@ export const tui: TuiPlugin = async (api) => {
           } catch {}
         }
       } catch {}
-      // Server owns lifecycle: it unlinks the pending file after consuming the cancelled response.
+      // Keep the pending payload until the server consumes the cancellation response.
       api.ui.dialog.clear()
       currentBySession.delete(curSid)
       setTimeout(processPending, 150)

package/plugins/learn.ts

@@ -476,18 +476,29 @@ async function waitForResponse(directory: string, id: string, abort: AbortSignal
 }
 
 // Server-side inject (loopd pattern: host-adapter.ts:100 promptAsync + path.id + body.parts)
-const activeWatchers = new Map<string, fs.FSWatcher>()
+const activeWatchers = new Map<string, () => void>()
 function watchAndInject(client: any, directory: string, id: string, sessionID: string, buildText: (result: any) => string) {
   slog("watchAndInject start", id, sessionID)
   if (!sessionID) { slog("watchAndInject no sessionID", id); return }
+  activeWatchers.get(id)?.()
   const dir = pendingDir(directory)
   const respPath = path.join(dir, `response-${id}.json`)
   const claimPath = path.join(dir, `response-${id}.claim-${process.pid}.json`)
   const pendingCandidates = [path.join(dir, `quiz-${id}.json`), path.join(dir, `quiz_batch-${id}.json`)]
-  const closeWatcher = () => { const w = activeWatchers.get(id); if (w) { try { w.close() } catch {}; activeWatchers.delete(id) } }
+  let watcher: fs.FSWatcher | undefined
+  let pollTimer: ReturnType<typeof setInterval> | undefined
+  let closed = false
+  const closeWatcher = () => {
+    if (closed) return
+    closed = true
+    try { watcher?.close() } catch {}
+    if (pollTimer) clearInterval(pollTimer)
+    if (activeWatchers.get(id) === closeWatcher) activeWatchers.delete(id)
+  }
+  activeWatchers.set(id, closeWatcher)
   const fire = async (attempt = 0): Promise<void> => {
     // Atomic single-consumer claim: exactly one process proceeds (fixes double-inject across processes)
-    try { fs.renameSync(respPath, claimPath) } catch { closeWatcher(); return } // already claimed/consumed → stand down
+    try { fs.renameSync(respPath, claimPath) } catch { return } // no answer yet, or another process claimed it
     let data: any
     try {
       data = JSON.parse(fs.readFileSync(claimPath, "utf8"))
@@ -547,14 +558,16 @@ function watchAndInject(client: any, directory: string, id: string, sessionID: s
     }
     if (!ok) {
       slog("watchAndInject inject FAILED, preserved", id, effectiveSessionID, String(firstErr).slice(0,200))
-      try { fs.renameSync(claimPath, path.join(dir, `response-${id}.failed-${Date.now()}.json`)) } catch {}
+      closeWatcher()
+      try { fs.renameSync(claimPath, respPath) } catch {
+        try { fs.renameSync(claimPath, path.join(dir, `response-${id}.failed-${Date.now()}.json`)) } catch {}
+      }
       try {
         await client.app.log({ body: { service: "learn", level: "error", message: `inject FAILED for ${effectiveSessionID} (orig ${sessionID})`, extra: { id } } })
       } catch {}
-      closeWatcher()
       return
     }
-    // Success: server owns lifecycle — consume claim + pending (TUI no longer deletes pending)
+    // Success: consume claim + defensively try pending too (TUI is the primary owner of pending deletion)
     try { fs.unlinkSync(claimPath) } catch {}
     for (const p of pendingCandidates) try { fs.unlinkSync(p) } catch {}
     closeWatcher()
@@ -564,10 +577,18 @@ function watchAndInject(client: any, directory: string, id: string, sessionID: s
     } catch {}
   }
   try {
-    const w = fs.watch(dir, (_e, filename) => { if (filename === `response-${id}.json`) void fire() })
-    w.on("error", () => {})
-    activeWatchers.set(id, w)
+    // Fire on ANY directory event, not just exact filename match — atomic tmp+rename writes can report
+    // a different filename (or no filename) on some fs.watch backends (notably macOS FSEvents). The claim
+    // rename inside fire() makes this safe to call spuriously: if respPath doesn't exist yet, it just no-ops.
+    watcher = fs.watch(dir, () => { void fire() })
+    watcher.on("error", () => {})
   } catch {}
+  // fs.watch is lossy by design. Polling keeps persisted answers moving after a TUI/server restart
+  // even when the filesystem event is dropped.
+  pollTimer = setInterval(() => {
+    if (fs.existsSync(respPath)) { void fire(); return }
+    if (!pendingCandidates.some((p) => fs.existsSync(p)) && !fs.existsSync(claimPath)) closeWatcher()
+  }, 500)
   // Recheck after arming to close the event gap (claim makes double-fire safe)
   if (fs.existsSync(respPath)) { slog("watchAndInject fast-path", id); void fire(); return }
 }
@@ -803,14 +824,20 @@ Return ONLY JSON: {"inferred":[2],"semanticCorrect":false,"reason":"...","isIDK"
       const out = { id: data.id, inferredIndices: inferred, inferredValues, semanticCorrect, reason, isIDK, classifySessionID: (llmRes as any)?.sessionID, note: data.note, at: Date.now() }
       try { fs.writeFileSync(respPath, JSON.stringify(out), "utf8"); slog("classify response written", data.id, inferred.join(",")) } catch {}
     }
+    const sweep = () => {
+      try {
+        for (const f of fs.readdirSync(dir).filter(f => f.startsWith("classify-") && !f.startsWith("classify-response-"))) {
+          void processClassify(f)
+        }
+      } catch {}
+    }
     // Initial sweep
+    sweep()
     try {
-      for (const f of fs.readdirSync(dir).filter(f => f.startsWith("classify-") && !f.startsWith("classify-response-"))) {
-        void processClassify(f)
-      }
-    } catch {}
-    try {
-      const w = fs.watch(dir, (_e, filename) => { if (filename) void processClassify(filename) })
+      // Re-scan on ANY directory event rather than trusting the reported filename — atomic tmp+rename
+      // writes (used by the TUI) can report a different filename (or none) on some fs.watch backends
+      // (notably macOS FSEvents), which would otherwise silently drop classify requests.
+      const w = fs.watch(dir, () => sweep())
       w.on("error", () => {})
       // Keep watcher alive; store to avoid GC? No need.
     } catch {}
@@ -1045,9 +1072,9 @@ Return ONLY JSON: {"inferred":[2],"semanticCorrect":false,"reason":"...","isIDK"
     tool: {
       // ── quiz: graded question ────────────────────────────────────────
       quiz: tool({
-        description: "Ask the user a GRADED question with a known correct answer, then grade and give feedback. Unlike the native `question` tool (which collects preferences with no right answer), `quiz` has a correct answer, marks selection right/wrong, reveals correct answer, and shows explanation. Use to assess understanding before teaching and for retrieval practice after. Options-only: single/multi-select plus auto 'I don't know'. No free-text. For non-graded questions use the native `question` tool.",
+        description: "Ask the user a GRADED question with a known correct answer, then grade and give feedback. Unlike the native `question` tool (which collects preferences with no right answer), `quiz` has a correct answer, marks selection right/wrong, reveals the correct answer, and shows an explanation. The TUI interaction is asynchronous, so call `quiz` ALONE in an assistant turn: never call it in parallel or in the same response with native `question`, another `quiz`, `quiz_batch`, or any other user-input tool. When the result says displayed/waiting, end the turn immediately; the answer will be injected as a new turn. Only call native `question` after `quiz` if its result explicitly requests the no-TUI fallback. Use to assess understanding before teaching and for retrieval practice after. Options-only: single/multi-select plus auto 'I don't know'. No free-text. For non-graded questions use the native `question` tool.",
         args: {
-          question: tool.schema.string().describe("Single quiz question to ask. One per call."),
+          question: tool.schema.string().describe("Single quiz question to ask. Call this tool alone; do not combine it with another user-input tool in the same turn."),
           details: tool.schema.string().optional().describe("Extra context shown under question."),
           options: tool.schema.array(tool.schema.object({
             label: tool.schema.string().describe("Display label"),
@@ -1130,7 +1157,7 @@ Return ONLY JSON: {"inferred":[2],"semanticCorrect":false,"reason":"...","isIDK"
             }
           }
           if (tuiAlive) {
-            return `[quiz displayed in TUI — waiting for your answer in the popup. I'll continue once you respond.]`
+            return `[quiz displayed in TUI - waiting for the user's answer in the popup. STOP this assistant turn now. Do not call \`question\`, another tool, or ask another question in text. The answer will be injected as a new turn.]`
           }
           // ── Fallback: console TTY (NEVER inside opencode TUI — readline steals raw mode + mouse SGR `^[[<35;...M` and garbles alt-screen)
           // Inside opencode `OPENCODE=1` is always set, so skip readline and use instruction fallback that works with native `question` tool.
@@ -1190,7 +1217,7 @@ Return ONLY JSON: {"inferred":[2],"semanticCorrect":false,"reason":"...","isIDK"
 
       // ── quiz_batch: optional deck — quiz 1/3 → 2/3 → 3/3 in one dialog, one inject
       quiz_batch: tool({
-        description: "Batch version of quiz — shows 2-8 graded questions as a deck (Quiz 1/3 → 2/3 → 3/3) in one beautiful TUI, then one combined inject. Use when you want multiple probes without separate tool calls. Each entry has same schema as quiz.",
+        description: "Batch version of quiz - shows 2-8 graded questions as a deck (Quiz 1/3 to 2/3 to 3/3) in one TUI, then injects one combined answer. The TUI interaction is asynchronous, so call `quiz_batch` ALONE in an assistant turn: never call it in parallel or in the same response with native `question`, `quiz`, another `quiz_batch`, or any other user-input tool. When the result says displayed/waiting, end the turn immediately; the answers will be injected as a new turn. Use when you want multiple non-adaptive checks in one deck. Each entry has the same schema as quiz.",
         args: {
           quizzes: tool.schema.array(tool.schema.object({
             question: tool.schema.string(),
@@ -1280,8 +1307,8 @@ Return ONLY JSON: {"inferred":[2],"semanticCorrect":false,"reason":"...","isIDK"
               return `[quiz_batch answered] ${normalized.length} quizzes\n` + lines
             })
             slog("quiz_batch watchAndInject armed", id, "alive", isAlive)
-            if (isAlive) return `[quiz batch displayed in TUI — ${normalized.length} quizzes as deck Quiz 1/${normalized.length} → ${normalized.length}/${normalized.length}. Answer all, then one combined inject.]`
-            else return `[quiz batch displayed durably — TUI not alive yet, will appear on restart. Answer all, then one combined inject.]`
+            if (isAlive) return `[quiz batch displayed in TUI - ${normalized.length} quizzes as deck Quiz 1/${normalized.length} to ${normalized.length}/${normalized.length}. STOP this assistant turn now. Do not call \`question\`, another tool, or ask another question in text. The answers will be injected as a new turn.]`
+            else return `[quiz batch stored durably - TUI not alive yet, so it will appear on restart. STOP this assistant turn now. Do not call \`question\`, another tool, or ask another question in text. The answers will be injected after the user completes the deck.]`
           }
       }),
 

package/skills/teach/SKILL.md

@@ -72,6 +72,10 @@ The two principles are *how* you teach. This is *when* — the shape of a teachi
 
 **Accuracy is non-negotiable — verify, don't wing it from memory.** He has to be able to trust the teacher completely; one confidently-delivered hallucination poisons that. Working from memory alone is where LLMs invent things, so: **the moment you are even slightly unsure of any fact, name, date, formula, definition, or claim, stop and confirm it with a quick `researcher` subagent (via `task` with `subagent_type: "researcher"`) before you say it.** Pausing to verify is always acceptable — accuracy beats flow, every time. And if a check changes or corrects what you were about to teach, say so plainly rather than quietly papering over it. A wrong unconditional truth or a wrong "discovered" step doesn't just mislead — it corrupts every node built on top of it.
 
+### Interactive turns — one at a time
+
+**Interactive turns are serialized.** `quiz` is asynchronous in the OpenCode TUI: it returns control to the agent while its popup is still waiting for the learner. Therefore, call `quiz` **alone** in an assistant turn. Never call it in parallel with native `question`, `quiz_batch`, another `quiz`, or any other user-input tool. When its result says the quiz is displayed/waiting, end the turn immediately without asking another question in prose; the learner's answer will be injected as a new turn. Apply the same rule to `quiz_batch`. Only use native `question` after a quiz call when the quiz result explicitly requests that fallback because the TUI is unavailable.
+
 ### Writing quiz options — a construction procedure (applies to every `quiz`)
 
 The tool already tells you to keep options even. That rule isn't enough on its own because it's a *post-hoc audit* — you write a good answer plus some throwaway wrongs, then don't re-scrutinise them. The tell is baked in before any check runs. So don't audit afterwards; **build the options so evenness is automatic**:
@@ -85,9 +89,11 @@ If, reading the finished set cold, you can still tell which is right without kno
 
 ### Phase 1 — Probe (never skip this)
 
-You can't teach into his zone of proximal development without knowing where its edges are, and you can't aim the teaching without knowing what he's actually reaching for. Two separate unknowns, two separate tools — keep the boundary clean:
+You can't teach into his zone of proximal development without knowing where its edges are, and you can't aim the teaching without knowing what he's actually reaching for. Two separate unknowns, two separate tools, and separate turns — keep the boundary clean. Resolve the goal first so you know which prerequisite strands are relevant, then probe those strands. Never launch the goal question and a quiz together.
 
-**1a. His current level — use `quiz`. This is a mapping job, not a spot-check.** Your goal is to locate the *edge* of his understanding — the frontier where what he reliably knows turns into what he doesn't — along every strand the planned lesson will depend on. Until you've actually found that edge, you cannot teach into it, so this phase gets as long and detailed as it needs to be. There is no rush.
+**1a. His learning goal — use native `question` only when needed.** Find out what he actually wants taught. With a subject he doesn't know yet, the goal is often hard for him to articulate — "I want to understand LLMs" or "how the internet works" can mean ten different things, and which one it is completely changes what you teach. If his request already makes the desired outcome concrete, accept it and do not ask again. Otherwise, interrogate the vision until it's concrete. This has no right answer, so it's `question`, never `quiz`. Do not use `quiz` or `quiz_batch` for the goal — goal has no correct answer. Wait for this answer before starting 1b.
+
+**1b. His current level — use `quiz`. This is a mapping job, not a spot-check.** Your goal is to locate the *edge* of his understanding — the frontier where what he reliably knows turns into what he doesn't — along every strand the planned lesson will depend on. Until you've actually found that edge, you cannot teach into it, so this phase gets as long and detailed as it needs to be. There is no rush.
 
 **The edge is only located when it's bracketed.** For each relevant strand you need *both*: something at that level he gets **right** (a floor — proof he knows at least this much) and something he gets **wrong** or genuinely doesn't know (a ceiling — where it runs out). The edge sits between them. One side alone tells you almost nothing.
 
@@ -98,9 +104,7 @@ You can't teach into his zone of proximal development without knowing where its
 
 Do not advance to Phase 2 until, for each goal-relevant strand, you can state concretely both what he has and where it ends. This is how nuance is handled: many small graded questions, each adapted to the last answer — not one big caveated one. Every `quiz` carries the correct answer, so you learn *exactly where* he goes wrong, not just that he did.
 
-**Guardrail — one quiz at a time:** Call exactly **one** `quiz` per turn and wait for the user's answer (injected via the TUI) before the next probe. Never call `quiz_batch` or multiple `quiz` in parallel for Phase 1 — the next question must adapt to the last answer.
-
-**1b. His learning goal — use native `question`.** Find out what he actually wants taught. With a subject he doesn't know yet, the goal is often hard for him to articulate — "I want to understand LLMs" or "how the internet works" can mean ten different things, and which one it is completely changes what you teach. Interrogate the vision until it's concrete. This has no right answer, so it's `question`, never `quiz`. Do not use `quiz` or `quiz_batch` for the goal — goal has no correct answer.
+**Guardrail — one quiz at a time:** Call exactly **one** `quiz` per turn, call no other user-input tool in that turn, and stop immediately after the quiz reports that it is waiting. Wait for the user's answer (injected via the TUI) before the next probe. Never call `quiz_batch` or multiple `quiz` in parallel for Phase 1 — the next question must adapt to the last answer.
 
 ### Phase 2 — Plan (think hard here)
 
@@ -108,7 +112,7 @@ This is the highest-leverage step; don't rush it. With his level and his goal no
 
 - **Scope the field first with a `researcher` subagent.** Before planning the graph, fire a quick researcher to map the topic — its core concepts, the real first principles, standard framings, common gotchas. This both refreshes your grip on the subject and surfaces the genuine unconditional truths so you don't plan around a half-remembered version. Cheap, and it makes the whole plan more accurate.
 - What are the unconditional truths this rests on? Is there a clean atomic unit ("ALL X is done through {____}")?
-- Which of those does he already hold (from Phase 1a)? Build from there — not below it, not above it.
+- Which of those does he already hold (from Phase 1b)? Build from there — not below it, not above it.
 - What's the motivated discovery path from those truths to his goal? Where does each step come from — why would anyone reach for it?
 - Socratic or expository for each stretch, given the topic and his energy?
 
@@ -116,7 +120,7 @@ A good plan is what makes the teaching feel inevitable instead of arbitrary.
 
 **Then present the plan in chat — always, before any teaching.** Two parts:
 
-1. **The approach, in prose.** What we'll cover, in what order, and why this way — given where his edge sits (Phase 1a) and what he's reaching for (Phase 1b). A few freeform sentences.
+1. **The approach, in prose.** What we'll cover, in what order, and why this way — given what he's reaching for (Phase 1a) and where his edge sits (Phase 1b). A few freeform sentences.
 2. **The dependency map.** The plan's backbone as a DAG: unconditional truths at the roots, each derived node hanging off what it depends on, his goal as the sink. Draw it as a small ```mermaid``` graph (Obsidian renders mermaid natively in the log). This map *is* the teaching order — Phase 3 builds it node by node. Keep it small: few nodes, short labels — a map, not the territory.
 
 **Stress-test the roots before presenting.** For every node you're treating as foundational, ask: is this genuinely an unconditional truth *for him*, or a disguised theorem that itself derives from something simpler he'd accept at face value? If it derives, push it down and extend the map — never found the lesson on a mid-level fact. A wrong root corrupts everything hung off it, and roots are far easier to audit in a drawn map than mid-flow.