instar 1.3.108 → 1.3.110

package/upgrades/1.3.110.md

@@ -0,0 +1,55 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**The mentor autonomous-fix loop now spawns its per-cycle session with NO project
+MCP servers — fixing a headless boot-hang found by dogfooding the loop live.**
+
+The loop (shipped dark in v1.3.109) starts a full-tool Opus session each cycle. A
+headless `claude -p` spawn inherits the project `.mcp.json`, which includes
+interactively-authenticated remote MCP servers (Fathom's `mcp-remote`, the
+claude.ai connectors). Those can't complete their OAuth handshake headless, so
+the session hung on MCP boot — observed live at ~4.5 min, 0.1% CPU, no transcript,
+parked event loop — and never ran its cycle. The spawn was otherwise correct
+(opus, full tools, the real goal); only MCP-loading jammed it.
+
+The loop session now spawns with `--strict-mcp-config --mcp-config '{"mcpServers":{}}'`
+(zero MCP servers). It needs none — it drives the mentee over Telegram and ships
+fixes with built-in tools. A headless spawn that stalled now boots in ~9s. The
+flag is opt-in (`spawnSession({ disableProjectMcp: true })`); every other spawn
+keeps its MCP. The `--allowedTools` and new MCP-disable splices are unified in one
+tested pure helper (`claudeHeadlessExtraFlags`).
+
+## What to Tell Your User
+
+Only relevant if you run the (off-by-default) mentor autonomous-fix loop. I
+dogfooded it live and found its background worker session was hanging on startup
+— it was trying to load login-required tools that can't sign in without a human,
+so it froze before doing any work. I fixed it so the loop's worker starts with a
+clean, minimal toolset and boots in seconds instead of hanging. Nothing changes
+for any other session — they keep all their tools. This is the observe-and-fix
+loop doing its job, just with me driving it this round.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| No-MCP headless spawn option | `spawnSession({ disableProjectMcp: true })` (opt-in; used by the mentor loop) |
+| Mentor loop session boots reliably | Automatic when `mentor.autonomousFix.enabled` — no more MCP boot-hang |
+
+## Evidence
+
+- **Live reproduction (before):** the first real loop session (`mentor-autoloop-…`)
+  spawned as `claude --dangerously-skip-permissions --model opus -p '…'` and sat
+  ~4.5 min at 0.1% CPU, no transcript written, main thread in `_pthread_cond_wait`;
+  child procs `@playwright/mcp` and `mcp-remote …fathom` alive at 0% CPU.
+- **Fix verified (after):** `claude --strict-mcp-config --mcp-config '{"mcpServers":{}}'
+  --model haiku -p '…'` in the same project returned in ~9s with no MCP boot.
+- **Tests:** `tests/unit/claude-headless-extra-flags.test.ts` (6, every branch incl.
+  the empty-MCP-config validity); `tests/e2e/mentor-onboarding-lifecycle.test.ts`
+  (+1: the production loop spawn passes the no-MCP flag). Framework-launch
+  regression suite (56) green. `tsc` + lint clean.
+- Side-effects: `upgrades/side-effects/loop-session-no-mcp.md`. Spec:
+  `docs/specs/LOOP-SESSION-NO-MCP-SPEC.md`.

package/upgrades/NEXT.eli16.md

@@ -2,81 +2,78 @@
 
 ## What this change is
 
-Your agent has a feature called the "Failure-Learning Loop" — it watches for
-things that go wrong (a CI run fails, a recent commit gets reverted, an
-internal health-check trips) and writes a little record so you can later ask
-"why do my agents keep breaking?" and get a real answer instead of vibes.
-
-The loop has a config switch for each kind of failure it watches. Some of
-those switches were checked in months ago but never connected to anything —
-flipping them on did literally nothing, the loop just pretended the source
-was active. That's exactly the failure mode the post-mortem yesterday named
-as "specced but not wired" — a real, repeat offender.
-
-This change does two things:
-
-1. **Loud warning when you flip on a switch that isn't wired up.** If you set
-   `monitoring.failureLearning.sources.regression: true` or
-   `monitoring.failureLearning.sources.degradation: [...]`, the agent now
-   says, at startup: "you turned this on but nothing implements it yet —
-   set it back off until the impl ships." Before, those switches were silent
-   no-ops.
-
-2. **A new automated check that catches a different bug class.** When you do
-   a fresh `instar init`, certain hooks get installed. When the agent
-   auto-updates, a different bit of code re-installs hooks. We had at least
-   one case in the last release where the two lists disagreed — a fresh
-   agent was missing a hook that existing agents had, because nobody had
-   noticed the divergence. The new check reads both lists and refuses
-   to commit any change that creates a new divergence (with a small
-   allowlist for documented technical debt).
+In JavaScript/TypeScript, you can write `try { ... } catch {}` — a block
+that says "do this, and if anything goes wrong, throw the error away
+and continue silently." It's three characters of body and zero
+explanation, and it's a really cheap shortcut that almost always means
+"I don't want to think about this right now."
+
+The problem: when an error gets thrown away silently, you don't find
+out about it from a stack trace or a log line. You find out about it
+when something downstream breaks, often hours later, often from a user.
+
+The worst recent example was the **PromptGate $452 incident**. There
+was a 5-second loop checking whether the LLM had hit its rate limit.
+Inside that loop, a bare `catch {}` was swallowing every actual
+rate-limit error. The loop kept burning credits at full speed —
+hundreds of times per minute, sometimes for hours — because nothing
+ever surfaced the problem. By the time someone noticed, we'd burned
+$452 we shouldn't have.
+
+This PR adds a unit-test lint that refuses any bare `catch {}` in
+production code (`src/**/*.ts`, excluding tests and code-generation
+hosts) unless it carries a comment annotation explaining WHY the
+silent swallow is safe.
 
 ## What already exists
 
-- The Failure-Learning Loop itself, with ledger + analyzer + API at `/failures/*`.
-- The `ci` and `revert` ingestion sources, which actually work and capture events.
-- The `regression` and `degradation` source flags in config defaults
-  (just no implementation behind them).
-- `PostUpdateMigrator` (the auto-update path) and `installHooks()`
-  (the fresh-init path), both of which write hooks to disk independently.
+- An older lint called `no-silent-fallbacks.test.ts` that catches a
+  related pattern: catches that return a degraded value (`return
+  null`, `return []`, etc.).
+- The `@silent-fallback-ok` comment annotation, already used in
+  several places (`TrustRecovery.ts`, `SyncOrchestrator.ts`, etc.).
+- `DegradationReporter` for emitting properly-tracked degradation
+  signals.
 
 ## What's new
 
-- Boot-time warning if `regression` or `degradation` source flag is on but
-  unimplemented.
-- Unit test that pins the source-flag-to-poller wiring so future regressions
-  fail the test suite instead of silently disabling the loop.
-- Unit test that diffs the fresh-init hook list against the auto-update hook
-  list and fails on any new divergence.
-- A small allowlist of currently-accepted divergences (six entries, with
-  rationale per entry; soft cap of ten so the list can't quietly grow).
+- A new lint test `tests/unit/no-empty-catch-blocks.test.ts` that
+  scans for truly empty `catch{}` blocks and fails on any new ones.
+- The seven existing bare `catch{}` sites are annotated in this same
+  PR — five in `src/paste/PasteManager.ts` (file cleanup that's
+  genuinely safe to silently fail) and three elsewhere. Each carries
+  a one-line rationale.
+- A focused regression check on `src/core/PromptGate.ts` — the file
+  that gave the post-mortem its poster-child incident. It can never
+  silently regress.
+- The lint's ratchet baseline starts at zero. New bare `catch{}` in
+  unannotated form fails the unit suite at commit time.
 
 ## What you need to decide
 
-Nothing. This is structural backstop, no configuration involved. Existing
-agents pick up the warning on next process restart (auto-update will trigger
-that). Future PRs that try to introduce a new fresh-init-vs-auto-update gap
-will fail their tests.
+Nothing. Lint-only. No runtime change, no config, no fleet migration.
 
 ## How to verify it worked after deploy
 
-If you haven't touched `monitoring.failureLearning.sources` in your config,
-you should see exactly the same behavior. If you flipped one of the
-unimplemented sources on, you'll see a one-line warning at startup.
-
-To start actually USING the Failure-Learning Loop on your agent, set
-`monitoring.failureLearning.sources.ci: true` and `sources.revert: true`
-in `.instar/config.json`. The substrate has been ready since late April;
-this PR just adds the tests around it. Echo's local config is being flipped
-out-of-band as a dogfooding step.
+Try writing a function with a bare `catch{}` in `src/`. Stage it. The
+pre-commit gate's test step will fail with a clear message naming
+PromptGate and the post-mortem. Fix: add `// @silent-fallback-ok —
+<why>` above the catch, OR put a real body inside it.
 
 ## Why this matters more than it might look
 
-The 14-day fix-shape rate to main is around 19% — we've been shipping a lot
-of bugs and finding out from users instead of from instrumentation. The
-Failure-Learning Loop is the meta-trace that turns "we keep shipping bugs"
-into "here are the three patterns most of them share." But it was sitting
-unused because the ingestion sources were silent. This PR closes one half
-of that gap (the wiring-test + the unimplemented-source warning); flipping
-the working sources on for each agent closes the other half. Several more
-PRs from the same post-mortem will follow.
+This is the fifth post-mortem PR landing in roughly four hours. Each
+one closes a recurring bug class, not just one incident:
+
+- #542 — silent-403 on secret-externalization (config-reader didn't
+  survive the security upgrade).
+- #545 — failure-learning loop wiring + migration-parity tests.
+- #550 — failure-learning git reads opt into the source-tree read
+  escape hatch.
+- #551 — `gh pr merge` refused on red checks (the watch-exit-merge
+  class).
+- THIS — bare `catch {}` refused in production paths.
+
+Each of these patterns has cost real time + real money. Closing them
+at the structural level (a lint, a test, a hook) is much cheaper than
+relying on "we'll be careful next time."

package/upgrades/side-effects/dangerous-command-guard-gh-pr-merge-gate.md

@@ -0,0 +1,102 @@
+# Side-effects review — dangerous-command-guard gh-pr-merge gate
+
+## What changed
+
+`dangerous-command-guard.sh` (PreToolUse hook on the Bash tool) gains a new
+gate block that refuses `gh pr merge` invocations when any PR check is
+non-passing.
+
+- The gate runs `gh pr checks <num> --json name,state` (uses the current
+  branch's PR if no number is given on the command).
+- A check is "ok" iff its state is `SUCCESS`, `SKIPPED`, `SKIPPING`, or
+  `NEUTRAL`. Anything else (`FAILURE`, `PENDING`, `QUEUED`, etc.) is
+  non-passing.
+- `gh pr merge --auto` is allowed through — it's the documented async safe
+  path that only fires when checks pass.
+- All other shapes (`gh pr merge <num> --squash`, `gh pr merge --admin
+  <num>`, no-flag) are gated.
+- Pattern match is bounded to command-start boundary (`^`, `;`, `&&`, `||`,
+  `|`, `(`, or whitespace), so commands that merely mention "gh pr merge"
+  in a string literal (e.g. `echo "fix gh pr merge bug"`) do not trigger.
+
+The gate lives inline in `dangerous-command-guard.sh`, matching the existing
+safety-gate pattern (catastrophic / deployment-coherence / risky-commands
+blocks). Same content is duplicated in `src/commands/init.ts` (fresh-init
+copy) and `src/core/PostUpdateMigrator.ts` `getDangerousCommandGuard()`
+(auto-update copy), per the existing parity allowlist in
+`migration-parity-hooks.test.ts`.
+
+## Why
+
+This closes the **2026-05-27 PR #539 watch-exit-merge class**. Justin merged
+PR #539 (the better-sqlite3 ABI heal) on the back of `gh run watch` returning
+exit 0. But `gh run watch` returns 0 on workflow COMPLETION regardless of
+conclusion. The PR's branch-protection checks were RED (Type Check + 2 unit
+shards failing), and merging on the false-positive watch exit cost:
+- A fix-forward (#540) for the green-up of the same change.
+- A ~16-hour fleet outage on instar-codey when the ABI-heal regression hit
+  production.
+- A memory entry (`[feedback_never_merge_on_watch_exit_verify_checks]`)
+  warning against the pattern in the future, which is exactly the
+  "structure > willpower" antipattern this PR replaces.
+
+Per the post-mortem (PR #545), this is lever E: smallest of the remaining
+levers, closes the most embarrassing class. Pure structural enforcement —
+no relying on the agent to remember to check.
+
+## Risk surface
+
+- **`gh pr merge --auto` is allowed.** This is the documented async safe
+  path — async, fires only when checks pass, idempotent. Allowing it does
+  not weaken the gate.
+- **Pattern-bounded.** The command-start anchor (`(^|[;&|(\s])`) prevents
+  false-positives on string literals, comments, or commands that happen to
+  contain the literal phrase.
+- **No-PR fallback.** If no PR number is in the command line, the gate
+  consults `gh pr view --json number` to resolve the current branch's PR.
+  If that fails (e.g. not in a git repo, or no PR exists), the gate
+  exits silently — allowing the command. This is the documented behavior
+  of `gh pr merge` itself when no PR exists; we don't add new failure
+  modes.
+- **Skipped-checks tolerance.** `SKIPPED` / `SKIPPING` checks (e.g.
+  Contract Tests on non-tagged PRs) are explicitly OK. The most common
+  intentionally-skipped case in our pipeline.
+- **Default-on for new and existing agents.** New agents get it via fresh
+  init; existing agents get it via PostUpdateMigrator's always-overwrite
+  rewrite of `dangerous-command-guard.sh` on every auto-update tick.
+
+## Bug surfaces eliminated
+
+- A future "merged on a red CI shard because watch exited 0" incident is
+  structurally impossible from the dangerous-command-guard surface.
+- `gh pr merge --admin` with red checks is also blocked (the #539 incident
+  shape itself).
+- `gh pr merge` with PENDING checks (e.g. immediately after a push, before
+  CI has fired) is blocked — the agent must wait, OR use `--auto`.
+
+## Migration footprint
+
+`dangerous-command-guard.sh` is on the always-overwrite list (per
+`PostUpdateMigrator.migrateHooks`). Existing agents pick up the new gate on
+the next auto-update tick — typically within ~30 min of release. No config
+schema change, no per-agent migration.
+
+## Testing
+
+- Unit: `tests/unit/dangerous-command-guard-gh-pr-merge-gate.test.ts` — 10
+  tests. Two surface checks (both guard writers contain the gate block) +
+  eight behavioral checks (spawn the rendered hook with a mocked `gh`
+  binary on PATH, verify BLOCK on FAILURE / PENDING, ALLOW on SUCCESS /
+  SKIPPED, ALLOW on `--auto`, IGNORE non-`gh pr merge` commands, BLOCK on
+  `--admin` with red checks, BLOCK on no-PR-number with red current-branch
+  PR).
+- `tests/unit/migration-parity-hooks.test.ts` (from PR #545) still green:
+  the new gate landed in BOTH writers in lockstep, so no new gap surfaces.
+- `tsc --noEmit` clean.
+
+## Follow-ups
+
+- The other post-mortem levers from PR #545's "What Changed" still pending:
+  B (real-world-state fixture tests — biggest, separate conversation), D
+  (silent-failure ban lint — small, similar shape to PR #542's
+  secret-externalization lint).

package/upgrades/side-effects/failure-learning-source-tree-readok.md

@@ -0,0 +1,113 @@
+# Side-effects review — Failure-Learning git reads opt into sourceTreeReadOk
+
+## What changed
+
+Three `SafeGitExecutor.readSync` call-sites used by the Failure-Learning Loop
+now pass `sourceTreeReadOk: true`:
+
+1. `src/monitoring/RevertDetector.ts` — default `git` injection (used when the
+   constructor caller doesn't supply an override).
+2. `src/server/AgentServer.ts` — the `FailureAttributionEngine`'s
+   `commitTouchedFiles` (uses `git show --name-only`).
+3. `src/server/AgentServer.ts` — the `CiFailurePoller`'s `resolveRepo` (uses
+   `git remote get-url origin`).
+
+All three verbs (`log`, `show`, `remote`) are already in
+`SOURCE_TREE_READ_TIER_VERBS`, so the flag legitimately opens the read on the
+instar source tree without weakening the destructive-write protection.
+
+## Why
+
+The 2026-05-29 pipeline post-mortem (PR #545) flipped the
+`monitoring.failureLearning.sources.ci: true` and `sources.revert: true`
+flags on Echo. Within an hour of the flip — and continuing for several hours
+after — `logs/server-stderr.log` filled with
+
+```
+[WARN] [revert-detector] SourceTreeGuardError: Refusing to run
+failure-learning:revert-detect against the instar source tree (requested
+dir: /Users/justin/.instar/agents/echo, resolved git root: /Users/justin/
+.instar/agents/echo).
+```
+
+once per detector tick (every ~5 min). `GET /failures/analysis` reported
+`total: 1` (the manually-diagnosed entry I posted that morning) because
+every actual CI/revert ingestion attempt was silently bouncing off the
+guard. The detector's `onError` callback logged a warn and then returned,
+so the ledger never saw the event.
+
+`SourceTreeGuard` exists to prevent destructive operations against the
+instar source tree (the 2026-04-22 incident class). The escape hatch
+`SafeGitOptions.sourceTreeReadOk: true` is the documented opt-in for
+legitimate read-tier calls against an agent's own checkout — already used
+by the worktree-manager and the canonical-ref reconciler. The
+Failure-Learning Loop's revert-detector and CI-poller are exactly the
+same shape: they read the agent's own repo to do their job. The fix is
+to opt them into the existing escape hatch, not to weaken the guard.
+
+The substrate (`SOURCE_TREE_READ_TIER_VERBS`, `sourceTreeReadOk`,
+`isSourceTreeCheckBypassed`) was already shipped — this PR just wires
+the failure-learning consumers into it.
+
+## Risk surface
+
+- **No new destructive-shape exposure.** `sourceTreeReadOk: true` only
+  bypasses the source-tree check for verbs in the explicit
+  `SOURCE_TREE_READ_TIER_VERBS` set. Destructive verbs still hit the
+  guard the same as before. `readSync` itself also fails-closed on any
+  non-read shape (via `isReadOnlyShape` + `READONLY_GIT_VERBS`) before
+  the source-tree check is even consulted.
+- **No fleet config change.** Default off agents see no behavior change.
+  Agents that have already opted in (only Echo today) start capturing
+  CI failures + reverts on the next process restart.
+- **Tests** — one unit (4 sub-tests, static introspection of the
+  call-shape across RevertDetector + AgentServer + the catch-all
+  failure-learning callsite scanner) and one integration (1 sub-test,
+  exercises the DEFAULT git invocation against the actual instar
+  source tree — the path the existing unit tests entirely mocked,
+  which is how the gap shipped silently in the first place). Both
+  positive- and negative-verified by removing the flag.
+
+## Bug surfaces eliminated
+
+- The failure-learning loop's `revert` source captures real reverts on
+  dogfooding agents (Echo).
+- The failure-learning loop's `ci` source can now resolve the GitHub
+  repo URL on dogfooding agents (it was silently returning `null` from
+  `resolveRepo` and skipping the entire poll).
+- Future failure-learning git reads added against the agent's source
+  tree must carry the flag — surfaced at commit time by the catch-all
+  test.
+
+## Migration footprint
+
+None. This is pure source-code wiring; no config schema change, no
+fleet migration required. Existing agents pick up the fix on next
+process restart (auto-update path).
+
+## Testing
+
+- Unit: `tests/unit/failure-learning-source-tree-readok-wiring.test.ts`
+  — 4 tests. Per-callsite positive checks + catch-all that scans the
+  failure-learning surface. Verified positive + destructive-negative
+  (removing the flag from RevertDetector → catch-all test fails as
+  expected).
+- Integration: `tests/integration/failure-learning-real-source-tree.test.ts`
+  — 1 test. Constructs RevertDetector with NO git override (forces the
+  default SafeGitExecutor.readSync path), points `cwd` at the test's own
+  repo root (which IS the instar source on every CI shard), asserts the
+  default invocation does not throw SourceTreeGuardError and returns a
+  real commit-subject string. Verified negative — removing the flag
+  makes the test fail with `SourceTreeGuardError`.
+
+## Follow-ups
+
+- Meta lesson: the existing RevertDetector + CiFailurePoller unit tests
+  mock `git`/`runGh` entirely, which is how this gap shipped silently.
+  This is an instance of post-mortem pattern #1 ("tested on fresh state,
+  not real-world state"). Post-mortem lever B (real-world-state fixture
+  test class) closes the broader pattern; until then, the catch-all
+  static-introspection test pins this specific class.
+- Echo's accumulated `[revert-detector] SourceTreeGuardError` warnings
+  in `server-stderr.log` will stop appearing after the v1.3.109+
+  auto-update lands.

package/upgrades/side-effects/loop-session-no-mcp.md

@@ -0,0 +1,65 @@
+# Side-effects review — Mentor loop session spawns with no project MCP
+
+**Spec:** `docs/specs/LOOP-SESSION-NO-MCP-SPEC.md`
+**Change:** the mentor autonomous-fix loop spawns its per-cycle Opus session with
+no project MCP servers, so a headless spawn doesn't hang on auth-required remote
+MCP boot. Found by the live dogfood of the loop (#554).
+**Class:** mentor-loop reliability fix (the feature ships dark).
+
+## What changed
+
+- **`src/core/frameworkSessionLaunch.ts`** (+1 export) — `claudeHeadlessExtraFlags(opts)`:
+  the single pure builder for the claude-code headless flags spliced before `-p`
+  (the existing `--allowedTools` scope + the new `--strict-mcp-config --mcp-config
+  '{"mcpServers":{}}'` no-MCP spawn). Returns `[]` for non-claude / no options.
+- **`src/core/SessionManager.ts`** — new opt-in `spawnSession({ disableProjectMcp })`;
+  the two inline flag-splice blocks (`--allowedTools` + the new MCP-disable) are
+  replaced by one call to `claudeHeadlessExtraFlags`.
+- **`src/server/AgentServer.ts`** — `spawnLoopSession` passes `disableProjectMcp: true`.
+
+## Blast radius
+
+- **Other spawn callers:** unchanged. `disableProjectMcp` is opt-in (default
+  unset). Interactive sessions, mentee-handle spawns, Stage-A, and jobs leave it
+  unset ⇒ byte-identical argv to today (project MCP loads as before).
+- **`--allowedTools` behaviour:** preserved exactly — same flags, now built by the
+  shared helper instead of an inline splice. Covered by the existing
+  framework-launch unit suite (56 tests still green) + the new helper test.
+- **Codex spawns:** unaffected — the helper returns `[]` for non-claude
+  frameworks (Codex MCP wiring is separate, via sandbox modes).
+- **MCP for the loop session:** the loop drives the mentee over Telegram (bash +
+  relay / a2a HTTP) and ships fixes with built-in tools — it used no MCP, so
+  removing it has no functional loss, only removes the boot hazard.
+
+## What could break (and why it doesn't)
+
+- **Loop needs an MCP tool?** It doesn't — it uses built-in Bash/Edit/Read/Write
+  + git/gh via Bash, and Telegram via the relay script. If a future loop variant
+  needs a specific MCP, pass a curated `--mcp-config` rather than the project one.
+- **`--mcp-config` inline-string support?** Verified against the installed claude
+  CLI: `--mcp-config '{"mcpServers":{}}'` is accepted and starts zero servers
+  (a headless `-p` run that otherwise stalled booted in ~9s).
+- **Splice position?** The helper's flags are spliced before `-p` exactly like the
+  prior `--allowedTools` code; argv structure is unchanged otherwise.
+
+## Security
+
+No new external input / network / auth / fs surface. The change REMOVES MCP
+servers from one spawn path (strictly fewer external connections). The empty MCP
+config is a constant inline string.
+
+## Migration parity
+
+Server-internal session-spawn code — every agent gets it by running the new
+build. No config, schema, hook, or CLAUDE.md change. No PostUpdateMigrator entry.
+
+## Rollback
+
+Revert the commit, or stop passing `disableProjectMcp`. No persisted state.
+
+## Tests
+
+`tests/unit/claude-headless-extra-flags.test.ts` (+6): every helper branch incl.
+the empty-MCP-config validity. `tests/e2e/mentor-onboarding-lifecycle.test.ts`
+(+1 assertion): the production loop spawn passes `disableProjectMcp: true`.
+Framework-launch regression suite (56 tests) green. `tsc` + `npm run lint` clean.

package/upgrades/side-effects/mentor-autonomous-fix-loop.md

@@ -0,0 +1,79 @@
+# Side-effects review — Mentor Autonomous-Fix Loop ("just be Echo")
+
+**Spec:** `docs/specs/MENTOR-AUTONOMOUS-FIX-LOOP-SPEC.md`
+**Change:** a config-gated GUARDIAN path on the mentor heartbeat that keeps one
+full-tool Opus session alive on the manual dogfooding loop (assign → observe →
+FIX as a fleet PR → report) instead of the haiku observe-and-log pipeline.
+**Class:** mentor capability (off by default; opt-in per agent).
+
+## What changed
+
+- **`src/scheduler/MentorAutonomousGuardian.ts`** (new) — pure
+  `runAutonomousGuardian(deps)` gate sequence + `buildAutoloopGoal(params)`
+  deterministic goal prompt. No I/O; every side-effect injected.
+- **`src/scheduler/MentorOnboardingRunner.ts`** — new `MentorAutonomousFixConfig`
+  type + optional `MentorConfig.autonomousFix`; three optional guardian services
+  on `MentorRunnerServices`; widened `MentorRunReason` + `sessionName` on
+  `MentorRunResult`; `tick()`/`startTick()` route to the guardian when
+  `autonomousFix.enabled` (regardless of `mode`); new private `autonomousTick`.
+- **`src/config/ConfigDefaults.ts`** — `mentor.autonomousFix` dark default added
+  to `SHARED_DEFAULTS`.
+- **`src/server/AgentServer.ts`** — wired `loopSessionAlive`, `spawnLoopSession`
+  (full-tool Opus spawn), `buildAutoloopGoal` into `buildMentorRunner`.
+- **`src/core/PostUpdateMigrator.ts`** — CLAUDE.md mentor section gains the
+  autonomous-fix paragraph (new-agent text + a content-sniffed parity paragraph
+  for agents that already have the section).
+
+## Blast radius
+
+- **Observe-pipeline:** unchanged. The guardian is a separate branch reached only
+  when `autonomousFix.enabled`. With the dark default, every existing agent runs
+  exactly the prior code path.
+- **`runMentorTick` (pure):** untouched — the guardian is a sibling module, not a
+  modification of the tick core.
+- **Config reads:** `readMentorConfigFromDisk` already spreads
+  `{...DEFAULT_MENTOR_CONFIG, ...parsed.mentor}`; an absent `autonomousFix` reads
+  as `undefined` → disabled. Safe for every config on disk today.
+- **Session spawn:** the loop session uses the normal `spawnSession` path
+  (full-tool, like a regular session) — no new spawn machinery. The only new
+  behaviour is that, when ENABLED, the heartbeat can start a session; the four
+  gates bound that.
+- **Other subsystems / DB schema / HTTP routes:** none added or changed. The
+  guardian rides the existing `/mentor/tick` + `/mentor/status` routes.
+
+## What could break (and why it doesn't)
+
+- **Spawn-storm of expensive Opus sessions?** The single-instance gate
+  (`loopSessionAlive`) makes the heartbeat a no-op while a cycle is running; a
+  cycle outlives many heartbeats. Budget + min-interval add two more bounds.
+- **Enabled but no spawner wired?** Surfaces as `reason: 'spawn-failed'` with a
+  clear message in `/mentor/status.lastResult.error` — never a silent no-op.
+- **Autonomous code landing untested?** The spawned Echo passes the same husky +
+  instar-dev + CI gates as an interactive developer; those are framework-agnostic.
+- **`mode: 'off'` blocking it?** Intentional: the guardian is a distinct path that
+  keys on `enabled && autonomousFix.enabled`, so `mode` (which gates only the
+  haiku pipeline) does not disable it.
+
+## Security
+
+No new external input, network, auth, or fs surface. The loop session is spawned
+through the existing SessionManager with the agent's normal tool grant. Spawning
+is gated behind an opt-in dark flag.
+
+## Migration parity
+
+`mentor.autonomousFix` is in `SHARED_DEFAULTS`, so `migrateConfig`'s `applyDefaults`
+deep-merge adds the dark sub-block to existing agents on update
+(existence-checked). CLAUDE.md parity handled in `migrateClaudeMd`. No new job.
+
+## Rollback
+
+Set `mentor.autonomousFix.enabled: false` (or remove the block) — instantly back
+to the observe-pipeline. Revert the commit to remove the code; no persisted state,
+schema, or API contract is affected.
+
+## Tests
+
+48 mentor tests green across all three tiers (unit guardian + runner branch,
+integration routes, E2E production-wiring spawn with the Opus model + full tools),
+plus migration-parity unit tests. `tsc` clean.