instar 1.3.300 → 1.3.302

package/upgrades/1.3.302.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The mentor runner's lastResult now persists to the agent state directory (mentor-last-result.json, atomic write, corrupt-tolerant load) and rehydrates at construction, so GET /mentor/status .lastResult survives server restarts. Accepted ticks log one start line and one outcome line in the server log; previously only failures logged anything.
+
+## What to Tell Your User
+
+Nothing user-visible — diagnosis plumbing. If you ever ask "is the mentor loop doing anything?", the status endpoint and server log can now actually answer, even right after an update restart.
+
+## Summary of New Capabilities
+
+- GET /mentor/status .lastResult is restart-survivable (persisted per outcome, hydrated at boot).
+- Server log shows one line per accepted mentor tick and one per outcome (mentor tick accepted / tick result).
+
+## Evidence
+
+Live trace (2026-06-05): mentor enabled+live with a */15 schedule, yet lastResult was empty at every read and server.log had ZERO mentor outcome lines across three days — while the reap-log showed every job-mentor-onboarding session ending boot-purge-dead and only two tick POSTs were visible (deduped auth warnings). Restart cadence matched tick cadence, so the in-memory record was wiped before any read. Pinned by 5 new unit tests in tests/unit/MentorOnboardingRunner.test.ts (hydration at construction, absent-services back-compat, throwing load contained, save invoked on all three write paths, throwing save contained).

package/upgrades/mentor-tick-observability.eli16.md

@@ -0,0 +1,13 @@
+# The mentor loop's last outcome now survives restarts (and ticks show up in the log)
+
+The mentor system runs a heartbeat every 15 minutes: a small job session wakes up, pokes the server's "do one mentor tick" endpoint, and the outcome of that tick is supposed to be readable at the mentor status endpoint. Today, asking "is the mentor loop alive?" gave a permanently empty answer — `lastResult` was blank for days, even though the loop was configured on and live.
+
+Two compounding causes, both observability-only:
+
+1. **The last outcome lived only in memory.** Every server restart wiped it. On a day with frequent fleet releases, the server restarts about as often as the tick fires — so the one record of "what happened last tick" was erased before anyone could read it, essentially every time. The loop could have been working perfectly or completely broken; the status route couldn't tell you which.
+
+2. **Successful ticks logged nothing.** Only failures produced a log line. A server log with zero mentor lines was equally consistent with "every tick succeeded silently" and "no tick ever arrived" — we hit exactly this ambiguity while diagnosing it (three days of job sessions, two visible tick arrivals, zero outcome lines).
+
+The fix keeps the same shape as the runner's existing design: the host hands the runner two optional services — "load the last outcome" and "save the last outcome" — wired to a small JSON file in the agent's state directory (atomic write, corrupt-file-tolerant load). The runner hydrates from it once at construction and saves on every outcome write (disabled short-circuit, success, and failure all flow through one funnel). And every accepted tick now logs one line on start and one on completion, so the loop's pulse is visible in the server log.
+
+Nothing about WHAT the mentor does changed — no behavior, gating, or cadence change. If the file is missing or unwritable, the runner behaves exactly as before (in-memory only). Pure diagnosis plumbing for a loop that was flying blind.

package/upgrades/side-effects/mentor-tick-observability.md

@@ -0,0 +1,44 @@
+# Side-Effects Review — Mentor tick observability (durable lastResult + tick logging)
+
+**Version / slug:** `mentor-tick-observability`
+**Date:** `2026-06-05`
+**Author:** `instar-echo`
+
+## Summary
+
+`MentorRunnerServices` gains optional `loadLastResult`/`saveLastResult`; the runner hydrates `lastResult` once at construction and routes all three write paths (disabled short-circuit, success, failure) through one `setLastResult` funnel that persists best-effort. The host (`AgentServer.buildMentorRunner`) wires both to `<stateDir>/mentor-last-result.json` (atomic tmp+rename write; shape-checked, corrupt-tolerant load). `startTick` logs one line on acceptance and one on outcome.
+
+## Decision-point inventory
+
+- `MentorRunnerServices.loadLastResult` / `saveLastResult` — added — optional; absent ⇒ byte-for-byte old behavior (in-memory only).
+- `MentorOnboardingRunner.setLastResult` — added — single write funnel; persist failures contained (in-memory value already set).
+- Constructor hydration — added — try/catch contained; corrupt/missing ⇒ null (old start state).
+- `startTick` logging — added — two `console.log` lines per accepted tick; no logging change on the disabled/in-flight short-circuits (they stay quiet — they fire every 15 min when dark and would be log spam).
+- `AgentServer.buildMentorRunner` — modified — wires the two services only when `stateDir` exists; the persist file lives beside the existing `mentor-sent.jsonl` precedent.
+
+## Direction of failure
+
+- Old failure: the loop's only outcome record was wiped by every restart; success was silent in logs — "is the mentor alive?" was unanswerable from its own surfaces.
+- New behavior: outcome survives restarts; the log carries the loop's pulse.
+- Conservative failure direction: ALL new I/O is best-effort and contained — a missing stateDir, unreadable file, corrupt JSON, or full disk degrades to exactly the old in-memory behavior, never a crash, never a blocked tick.
+
+## Side-effects checklist
+
+1. **Over-block:** none possible — the change never gates or refuses anything; it records and logs only.
+2. **Under-block:** none — no authority added. A stale persisted lastResult after config flip-off is possible (file shows an old outcome while disabled writes overwrite it on the next tick POST) — acceptable: the disabled short-circuit itself writes `reason: disabled`, refreshing the file on the very next heartbeat.
+3. **Level-of-abstraction fit:** the runner owns WHEN to persist (its write funnel); the host owns WHERE/HOW (state-dir path + atomic write) — mirrors the existing `capture`/`deliverToMentee` service split and the `mentor-sent.jsonl` persistence precedent.
+4. **Signal vs authority compliance:** observability-only; no LLM, no gate. Log lines are signals.
+5. **Interactions:** the persisted shape is exactly the in-memory `MentorRunResult & { at }` — the status route serializes it identically whether hydrated or fresh. The hydrated value can briefly present a PRIOR generation's outcome after a restart until the next tick overwrites it — that is the feature (it is timestamped via `at`, so staleness is readable).
+6. **External surfaces:** GET /mentor/status semantics unchanged (same field, now durable). One new state file in the agent state dir. Two new log line shapes (`[mentor] tick accepted…` / `[mentor] tick result…`).
+7. **Rollback cost:** revert the commit; the state file is ignored by old code (no reader), safe to leave or delete.
+
+## Scope not taken
+
+- No fix for the job-session 1-min age-limit race (`expectedDurationMinutes: 1` vs heavy boot) — that is task #14's lean loop-worker territory; this slice makes the symptom DIAGNOSABLE first.
+- No X-Instar-AgentId header fix in the job template (auth deprecation warning) — separate small follow-up.
+- No grounding-config addition for the mentor job (JobLoader audit warning) — separate.
+- No change to tick cadence, gating, budget, or Stage-A/B behavior.
+
+## Rollback
+
+Revert the single commit. The runner returns to in-memory-only lastResult and silent successful ticks.

package/upgrades/side-effects/test-debt-rearm.md

@@ -0,0 +1,61 @@
+# Side-effects review — re-arm two quarantined CI gates + ambient-credential test hygiene
+
+Found during the 2026-06-05 full-suite triage (37 local failures enumerated and
+classified to root cause). Two of the repo's own source-content GUARDS had
+rotted while parked in the vitest.push.config.ts quarantine list — CI never ran
+them, so the exact bug classes they exist to catch reached main unnoticed.
+
+## 1. The change
+
+- **`src/monitoring/mcpProcessReaperDeps.ts`** — the `ps | egrep | grep -v`
+  shell pipeline (bare `execSync`) becomes `execFileSync` with argv arrays (no
+  shell, no interpolation surface); the coarse egrep pre-filter moves into JS
+  (`new RegExp(mcpGrepAlternation(), 'i')`) ahead of the existing precise
+  `matchMcpSignature` second stage. Behavior-preserving: same ps fields, same
+  two-stage filtering, same empty-string-on-failure contract.
+- **`src/core/PostUpdateMigrator.ts`** — `migrateFrameworkShadowCapabilities`
+  markers[] gains the coordination-mandate capability family
+  (`**Coordination Mandate**`, `**ReviewExchange (autonomous code review)**`,
+  `**Cutover Readiness**`). These are framework-agnostic HTTP capabilities in
+  BOTH templates.ts and the migrator, but were never mirrored to AGENTS.md /
+  GEMINI.md — a Codex/Gemini agent under a future mandate would never learn
+  `/mandate/evaluate` and would improvise around the gate (the Secret Drop
+  lesson). Mirroring is the existing idempotent slice-and-append mechanism;
+  no new mechanism.
+- **`tests/unit/feature-delivery-completeness.test.ts`** — tracks the mandate
+  family as featureSections (template ↔ migrator ↔ shadow-marker parity now
+  enforced) + the four content-sniff keys as alternate checks.
+- **`tests/unit/watchdog-bind-probe.test.ts` /
+  `tests/unit/serendipity-capture.test.ts`** — ambient-credential hygiene: both
+  spread `...process.env` into child envs, and on agent boxes the REAL
+  `INSTAR_AUTH_TOKEN` preempted the fixture tokens (Authorization-header and
+  HMAC-key assertions failed locally while green in CI). The sandboxes now
+  strip the ambient token; a test that wants one sets it explicitly.
+- **`vitest.push.config.ts`** — security.test.ts +
+  feature-delivery-completeness.test.ts REMOVED from the quarantine (re-armed;
+  both are deterministic source guards — the "environment-dependent" label was
+  wrong). TunnelManager.test.ts stays parked but its label now states the
+  truth: 22/29 tests fail because the suite predates the provider/tier rewrite
+  with the real reachability probe; rewrite tracked as a durable commitment.
+
+## 2. Blast radius
+
+- The reaper deps refactor is invisible to consumers (identical output
+  contract; the factory has no direct unit tests — covered by typecheck and
+  the McpProcessReaper suite, re-run green).
+- The markers addition only ever APPENDS missing sections to existing
+  AGENTS.md/GEMINI.md shadows on the next migration run — idempotent,
+  no-op for Claude-only installs, copies content verbatim from the
+  just-migrated CLAUDE.md so the files cannot drift.
+- Re-arming the two gates makes CI run 84 currently-green deterministic tests
+  it previously skipped. Risk is future-positive: regressions in these guards
+  now fail PRs instead of rotting.
+
+## 3. Test coverage
+
+- 5 directly-touched/affected files re-run green locally: 164 tests
+  (run WITH the real INSTAR_AUTH_TOKEN still exported — proving the hygiene
+  fix, since these exact assertions failed before it).
+- Full PostUpdateMigrator + shadow-capability surface: 49 files / 324 tests
+  green after the markers change.
+- `npx tsc --noEmit` clean.