chore: land PRs #36, #40, #42, #41 on main in one move

CHANGELOG.md

@@ -35,6 +35,20 @@ experience may change before `1.0.0`.
   separately through the skills CLI, not by `studyloop install agents`; its
   guide is published on the docs site as *Lesson Study Notes*
   (`docs/study-notes-skill.md`).
+- The mentor writes to the learning tier (issue #38, item 1 of the
+  learning-tier plan). A `record_teachback` MCP tool records a teach-back
+  score through the same validator the `studyloop teachback` CLI uses (the
+  CLI now delegates to it; its messages are unchanged), so a mentor session's
+  teach-back reaches tomorrow's recommendation instead of stopping at the
+  conversation. One `agents/shared/recording-protocol.md` carries a
+  machine-readable trigger table naming exactly the four append-only writers
+  (`log_topic`, `log_struggle`, `record_teachback`, `record_plan_learning`);
+  every harness definition and the built live persona name the same four,
+  and parity tests pin the names, the protocol hash and the absence of any
+  new pre-approval — recording stays prompt-per-call on every harness, by
+  owner decision. Scheduling mutators never fire from the protocol. A
+  child-process isolation guard proves the four writers land nowhere outside
+  the sandbox database. Owner decisions 1–5 are recorded in the plan (#34).
 
 ### Changed
 
@@ -62,6 +76,13 @@ experience may change before `1.0.0`.
   no learner saw the split; `spaced_repetition_due()` gains a keyword-only
   `now` for callers that already hold an instant, defaulting to the wall
   clock for everyone else.
+- A browser tab rejoining a session whose transport had already drained no
+  longer leaves *Task exception was never retrieved … StopAsyncIteration* in
+  the server log. The WebSocket pump pulls each transport event as its own
+  future; when a newer socket took the slot, or the client closed while the
+  drained future was already complete, the pump exited without reading that
+  future's `StopAsyncIteration`. The pump now retrieves the result of a done
+  pull future on every exit path.
 
 ## [0.5.0] - 2026-09-21
 

agents/claude/socratic-mentor.md

@@ -2,7 +2,7 @@
 name: socratic-mentor
 description: AuDHD-aware Socratic study mentor with spaced repetition, energy-adaptive sessions, network→DE concept bridges, and Clean Code/GoF discovery patterns
 category: communication
-tools: Read, Write, Grep, Bash
+tools: Read, Write, Grep, Bash, mcp__studyloop__get_concept_context, mcp__studyloop__get_study_history, mcp__studyloop__get_next_action, mcp__studyloop__get_topic_suggestions, mcp__studyloop__get_active_topics, mcp__studyloop__log_topic, mcp__studyloop__log_struggle, mcp__studyloop__record_teachback, mcp__studyloop__record_plan_learning
 ---
 
 # StudyLoop
@@ -19,6 +19,7 @@ See `agents/shared/knowledge-bridging.md` for configurable domain bridges.
 See `agents/shared/break-science.md` for active break protocol.
 See `agents/shared/wind-down-protocol.md` for end-of-session consolidation.
 See `agents/shared/teach-back-protocol.md` for teach-back scoring.
+See `agents/shared/recording-protocol.md` for when the mentor writes: `record_teachback`, `log_struggle`, `log_topic`, `record_plan_learning` — named on every harness, prompt-per-call where the harness prompts.
 
 ## Identity
 

agents/codex/AGENTS.md

@@ -12,6 +12,7 @@ See `agents/shared/knowledge-bridging.md` for configurable domain bridges.
 See `agents/shared/break-science.md` for active break protocol.
 See `agents/shared/wind-down-protocol.md` for end-of-session consolidation.
 See `agents/shared/teach-back-protocol.md` for teach-back scoring.
+See `agents/shared/recording-protocol.md` for when the mentor writes: `record_teachback`, `log_struggle`, `log_topic`, `record_plan_learning` — named on every harness, prompt-per-call where the harness prompts.
 
 ## Identity
 

agents/kiro/study-mentor/persona.md

@@ -29,7 +29,7 @@ Follow the unified session protocol in `agents/shared/session-protocol.md`:
 - One question at a time. Stop. Wait for response.
 - Network→DE bridges for every new concept
 - Max 3-4 concepts per explanation, TL;DR at top, mermaid diagrams for structure
-- Record progress: `uv run tutor-checkpoint <skill-name> --notes "<notes>"`
+- Record what the learner agreed, when `agents/shared/recording-protocol.md` says to: `record_teachback`, `log_struggle`, `log_topic`, `record_plan_learning` (the `@studyloop` MCP tools). Say so in one line, then the next question.
 
 ## Session Types
 
@@ -76,10 +76,12 @@ studyloop review                  # What's due for review?
 studyloop struggles               # Recurring struggle topics
 studyloop wins                    # Show learning wins
 
-# Progress tracking
+# Progress tracking — the mentor writes through MCP (see recording-protocol.md):
+#   @studyloop/record_teachback, @studyloop/log_struggle, @studyloop/log_topic,
+#   @studyloop/record_plan_learning. The CLI below is the human's path to the same rows.
 studyloop progress "<concept>" -t <topic> -c <confidence>
-uv run tutor-checkpoint <skill-name> --notes "<notes>"
-session-query search "<skill-name>"   # read back prior checkpoints for a skill
+studyloop teachback "<concept>" -t <topic> --score "3,3,4,3,2" --type structured
+session-query search "<skill-name>"   # read back prior sessions for a skill
 
 # Cross-machine sync
 studyloop state pull              # Get latest from hub
@@ -100,3 +102,4 @@ Configured in `~/.config/studyloop/config.yaml`
 - `agents/shared/audhd-framework.md` — Complete AuDHD cognitive support
 - `agents/shared/socratic-engine.md` — Questioning methodology
 - `agents/shared/network-bridges.md` — Network→DE concept bridges
+- `agents/shared/recording-protocol.md` — When the mentor writes (`record_teachback`, `log_struggle`, `log_topic`, `record_plan_learning`)

agents/manifest.json

@@ -2,92 +2,96 @@
   "version": 1,
   "agents": {
     "claude/socratic-mentor.md": {
-      "hash": "b0be77358df99a1b",
-      "updated": "2026-09-14"
+      "hash": "2bd4f5ebfdd9f045",
+      "updated": "2026-09-23"
     },
     "claude/study-plan-architect.md": {
       "hash": "19f1a1c0853cacf9",
-      "updated": "2026-09-18"
+      "updated": "2026-09-23"
     },
     "codex/AGENTS.md": {
-      "hash": "7e6c1a0d534b65f7",
-      "updated": "2026-09-14"
+      "hash": "4a9d027b2cf0207e",
+      "updated": "2026-09-23"
     },
     "kiro/study-mentor.json": {
       "hash": "21f51c19993e7ce4",
-      "updated": "2026-09-16"
+      "updated": "2026-09-23"
     },
     "kiro/study-plan-architect.json": {
       "hash": "ab42104634985d3e",
-      "updated": "2026-09-16"
+      "updated": "2026-09-23"
     },
     "opencode/plugins/studyloop-session-export.js": {
       "hash": "769ed9efdda111a9",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     },
     "opencode/study-mentor.md": {
-      "hash": "f91a0b52fd59e80f",
-      "updated": "2026-09-14"
+      "hash": "b7acf2cea171b4f1",
+      "updated": "2026-09-23"
     },
     "opencode/study-plan-architect.md": {
       "hash": "40057646dc674008",
-      "updated": "2026-09-18"
+      "updated": "2026-09-23"
     },
     "pi/AGENTS.md": {
-      "hash": "03355b0aa919ef6b",
-      "updated": "2026-09-14"
+      "hash": "f8528bdcc97b7909",
+      "updated": "2026-09-23"
     },
     "pi/extensions/studyloop-session-export.ts": {
       "hash": "5169fade780f0229",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     },
     "shared/audhd-framework.md": {
       "hash": "8b694064b100741f",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     },
     "shared/break-science.md": {
       "hash": "74541a44431f7f6a",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     },
     "shared/knowledge-bridging.md": {
       "hash": "33edec1cceac2e36",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     },
     "shared/network-bridges.md": {
       "hash": "8af4732b77cc15ae",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
+    },
+    "shared/recording-protocol.md": {
+      "hash": "21d8b0f8d20e0737",
+      "updated": "2026-09-23"
     },
     "shared/session-db-mandate.md": {
       "hash": "bdf22a3da57da972",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     },
     "shared/session-protocol.md": {
       "hash": "7f4f0c2cf9e3eb53",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     },
     "shared/socratic-engine.md": {
       "hash": "42738fba9479ec14",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     },
     "shared/teach-back-protocol.md": {
-      "hash": "09ee534106322244",
-      "updated": "2026-09-20"
+      "hash": "5512b099237e8f30",
+      "updated": "2026-09-23"
     },
     "shared/wind-down-protocol.md": {
       "hash": "5b1ec3303b8d1086",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     },
     "skills/studyloop-session-memory/SKILL.md": {
       "hash": "8d278dd01b1aa82d",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     },
     "skills/studyloop-xtiles-wind-down/SKILL.md": {
       "hash": "a2e84febb865f24d",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     },
     "skills/studyloop-xtiles-wind-down/references/harnesses.md": {
       "hash": "87a8ab3c4a133afa",
-      "updated": "2026-09-14"
+      "updated": "2026-09-23"
     }
   }
 }

agents/mcp/README.md

@@ -153,7 +153,7 @@ Requires a Google Cloud project with Calendar API enabled. See [setup guide](htt
 
 ## studyloop-mcp (Study tools)
 
-The `studyloop-mcp` server exposes 32 MCP tools: courses and review cards, the study backlog and
+The `studyloop-mcp` server exposes 33 MCP tools: courses and review cards, the study backlog and
 progress signals, lesson browsing, the live session, the `now` recommendation, and the learner's
 study plans (nine lifecycle tools plus `record_plan_learning`, every one through the same plan
 application layer the CLI and Web UI use — see `docs/agent-install.md`, "Study-plan tools over
@@ -199,6 +199,7 @@ server NAME is `studyloop`; `studyloop-mcp` is the console-script COMMAND, never
 | `get_active_topics` | The AuDHD three-topic active set vs the remaining backlog |
 | `log_topic` | Record a learning / struggling / insight signal mid-session |
 | `log_struggle` | Record a topic the learner struggled with, for later study |
+| `record_teachback` | Record the five agreed teach-back scores for a concept — the mentor's write after a teach-back |
 | `get_concept_context` | Concept dependency edges for a topic, with per-edge provenance and `coverage` — the prerequisite structure a mentor sequences from |
 | `get_next_action` | The same "what now?" recommendation the web `/api/now` endpoint gives — plan-aware when a plan is active |
 | `get_lesson_tree` | Browse the course-material tree: providers → courses → lessons |

agents/opencode/study-mentor.md

@@ -30,6 +30,7 @@ See `agents/shared/knowledge-bridging.md` for configurable domain bridges.
 See `agents/shared/break-science.md` for active break protocol.
 See `agents/shared/wind-down-protocol.md` for end-of-session consolidation.
 See `agents/shared/teach-back-protocol.md` for teach-back scoring.
+See `agents/shared/recording-protocol.md` for when the mentor writes: `record_teachback`, `log_struggle`, `log_topic`, `record_plan_learning` — named on every harness, prompt-per-call where the harness prompts.
 
 ## Identity
 

agents/pi/AGENTS.md

@@ -12,6 +12,7 @@ See `~/.agents/shared/knowledge-bridging.md` for configurable domain bridges.
 See `~/.agents/shared/break-science.md` for active break protocol.
 See `~/.agents/shared/wind-down-protocol.md` for end-of-session consolidation.
 See `~/.agents/shared/teach-back-protocol.md` for teach-back scoring.
+See `~/.agents/shared/recording-protocol.md` for when the mentor writes: `record_teachback`, `log_struggle`, `log_topic`, `record_plan_learning` — named on every harness, prompt-per-call where the harness prompts.
 
 ## Session Memory
 

agents/shared/personas/co-study.md

@@ -31,6 +31,12 @@ Always include a studyloop command in these situations — not as a separate blo
 
 Fill in the note with something specific to what they actually said — never leave it as a generic placeholder.
 
+The same four triggers, when the student confirms rather than runs the command themselves, are yours to write
+through the `studyloop-mcp` tools — `log_topic` at wind-down, `log_struggle` after two stuck rounds,
+`record_teachback` only for scores the student agreed, `record_plan_learning` only for a plan they are working
+against. `agents/shared/recording-protocol.md` is the table; the student drives, so ask before you write and say
+so in one line after.
+
 ## Energy Adaptation
 
 Check session energy level and elapsed time before responding:

agents/shared/personas/study.md

@@ -35,6 +35,23 @@ Status values: `learning` (in progress), `win` (understood), `insight` (aha mome
 
 **When logging, show the command inline.** Example: "That's a win — run: `studyloop topic "Decorators" --status win --note "grasped wrapping pattern"`"
 
+## Recording — what you write yourself
+
+`agents/shared/recording-protocol.md` is the one table that says when *you* write to the
+learning tier, through the `studyloop-mcp` tools (they may prompt the learner to approve the call;
+that is the harness's setting, not yours to change). Four writers, four triggers:
+
+- a teach-back has ended, you proposed five rubric scores, and the learner **agreed** them →
+  `record_teachback` (concept, topic, the five scores in order, the review type). Not agreed, not recorded.
+- two rounds stuck on one point → `log_struggle` (the question)
+- wind-down, one call per concept touched, with the status the learner confirms → `log_topic`
+- the session ran against an active plan and the learner agrees one line for its record → `record_plan_learning`
+
+A turn that matches none of these writes nothing. After a write, one short line — *"Recorded: window frame,
+structured, 15/20."* — then the next question. If the tool refuses or the learner declines the prompt, say so in
+one line and continue; never retry silently. The `studyloop topic` commands above remain the learner's own,
+visible path to the same rows.
+
 ## Win Recognition — IMPORTANT
 
 When a student demonstrates correct understanding, makes a connection, or has an aha moment:
@@ -83,6 +100,10 @@ studyloop content generate-cards ~/Obsidian/Personal/Study/<topic-or-course> --c
 Use local study sources, generated review artefacts, and session history by default. External source tools should be explicit opt-in plugins, not part of the active mentoring contract.
 
 **Progress & Review:**
+- `record_teachback` — record the five agreed teach-back scores for a concept (see Recording above)
+- `log_topic` — record a learning / struggling / insight / win / parked signal for a concept
+- `log_struggle` — record a question the learner was stuck on, for later study
+- `record_plan_learning` — append one learning record to an active study plan
 - `record_study_progress` — record a review result for a single card
 - `record_topic_progress` — update priority or resolve a backlog topic