# Instar Upgrade Guide — NEXT

<!-- bump: patch -->

## What Changed

**Mentor consumer — receiver wiring + anti-ping-pong tracker.** Closes the mentor round-trip
on Echo's side. Three coupled additions, all dark at the same `mentor.botToken` gate as the
prior PR (until the bot is configured, none of this runs):

- A new `OutstandingPromptTracker` — per-mentee, persistent across server restart — that
  refuses to send a new mentor prompt while a prior one is in flight within
  `replyTimeoutMs` (default 20 min, > the 15-min tick interval). This makes the original
  "ping-pong" concern structurally impossible at the cadence layer.
- A `mentor-reply` role-handler installed on the mentor-bot adapter via the receiver hook
  from the prior PR. When Codey replies, the handler clears the outstanding-prompt by
  correlation id + persists the reply to `mentor-replies.jsonl` for Stage-B forensics.
  The handler's closure has minimal capability — it cannot reach `spawnStageA` / scheduler
  / `deliverToMentee` / Threadline (structural anti-loop invariant).
- `deliverToMentee` integrates the tracker: sweeps orphans on each call + surfaces each
  one as a deduped `DegradationReporter` event (silent reply-loss is observable). Marks
  on successful send; defers if prior-prompt-in-flight.

---

`SourceTreeGuard` `sourceTreeReadOk` opt extended to `readSync` (defense-in-depth source-tree check on the read path) + `SOURCE_TREE_READ_TIER_VERBS` expanded to cover the canonical-ref read path the watchdog and reconciler use (`rev-parse`, `ls-tree`, `show`, `log`, `cat-file`, `merge-base`, `remote`). Caught dogfooding Echo on v1.3.38: the previous fix only opened `execSync` to `fetch`, but every downstream readonly verb still tripped the guard. With this PR landed, the watchdog completes a real tick against the agent's own instar source.

## What to Tell Your User

- Plumbing for the mentor feature — your concern about agents bouncing messages back and forth in a loop is now structurally impossible at the timing layer. Echo cannot send a new mentor message while it's still waiting on the prior reply, and if a reply never arrives an alert is raised instead of a silent retry. Stays completely dark until the mentor bot is configured.
- I can finally complete a real release-readiness watchdog tick against my own checkout. The first dogfood attempt caught a real safety-guard interaction; this update closes the loop so the watchdog can read what it needs without bypassing the broader policy.

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Mentor receiver + anti-ping-pong (dark) | Internal — `OutstandingPromptTracker` (per-mentee persistent state) blocks re-sends while a prior is in flight; mentor-reply role-handler clears the tracker on reply; orphan-sweep emits one deduped `DegradationReporter` event per orphaned correlation id |
| SourceTreeGuard `sourceTreeReadOk` on readSync | Pass `sourceTreeReadOk: true` to `SafeGitExecutor.run` / `readSync` for the read-tier verbs in `SOURCE_TREE_READ_TIER_VERBS` (now `fetch`, `rev-parse`, `ls-tree`, `show`, `log`, `cat-file`, `merge-base`, `remote`) |

## Evidence

**Net-new groundwork, not a bug fix.** 10 new unit tests for `OutstandingPromptTracker`,
all green. The receiver wiring + tracker integration in `AgentServer.deliverToMentee`
is the dark layer that the bot-setup live flow will exercise in the next PR.
`tsc --noEmit` clean. 50 mentor-stack tests across the staged build, all green.

For the SourceTreeGuard read-tier bypass: 7 unit tests covering both `execSync` and `readSync` paths with + without the opt, the closed-set invariant (10 destructive verbs explicitly NOT in the set), and the verbs the canonical-ref read path actually uses. Side-effects: `upgrades/side-effects/source-tree-guard-readsync-bypass.md`.
