instar 1.3.104 → 1.3.105

package/upgrades/side-effects/mentor-stage-a-robustness.md

@@ -0,0 +1,57 @@
+# Side-effects review — Mentor Stage-A: surface error + harden spawn
+
+**Spec:** `docs/specs/MENTOR-STAGE-A-ROBUSTNESS-SPEC.md`
+**Changes:** `src/scheduler/MentorOnboardingTick.ts`, `src/scheduler/MentorOnboardingRunner.ts`, `src/server/AgentServer.ts` (+ unit test)
+**Class:** mentor reliability + diagnosability fix.
+
+## What changed
+
+1. `MentorTickResult` gains `error?: string`.
+2. `runMentorTick`'s bare `catch {}` around `spawnStageA` → `catch (err)` that
+   captures the message into the returned result (`{…, error}`) + the finding
+   title.
+3. `MentorOnboardingRunner.startTick().catch` adds the same `error` field (for a
+   rejected `tick()`).
+4. `spawnStageA` (AgentServer.ts) wraps `spawnSession` in a single retry with a
+   3s backoff; on persistent failure throws `stage-a-spawn-failed: … — <cause>`.
+
+## Blast radius
+
+- **`/mentor/status` consumers:** purely additive — `lastResult` may now include
+  an `error` string on the failure path. No field removed/renamed.
+- **Healthy mentor ticks:** unchanged — new code runs only on the catch/failure
+  path or a throwing spawn.
+- **Stage-A two-hats isolation:** unchanged — still spawns with the empty
+  `STAGE_A_ALLOWED_TOOLS` grant; only error handling + a retry added.
+- **Public API / DB schema / config:** none changed. No new route (the
+  AgentServer change is inside an existing closure — E2E-PAIRING exempt).
+
+## What could break (and why it doesn't)
+
+- **The retry doubling spawn load?** Only on a spawn that already failed once,
+  and capped at 2 attempts with a 3s gap — negligible, and only on the
+  already-failing path.
+- **`error` field typing:** flows through `MentorRunResult extends
+  Omit<MentorTickResult,'reason'>` which keeps `error?`. `tsc` clean.
+- **Masking a persistent failure:** no — a persistent failure still throws after
+  2 attempts, now with the cause in the message.
+
+## Security
+
+No new external input / network / auth / fs surface. The surfaced `error` is an
+internal spawn/timeout message (no secrets).
+
+## Migration parity
+
+Server-internal scheduler/server code — every agent gets it by running the new
+build. No PostUpdateMigrator entry required.
+
+## Rollback
+
+Revert the commit. No persisted state, schema, or API contract affected.
+
+## Tests
+
+`tests/unit/MentorOnboardingRunner.test.ts` (+1): a throwing `spawnStageA` now
+surfaces `lastResult.error` with the real message (was swallowed). Full
+mentor/stage suite — 113 tests across 9 files — green; `tsc --noEmit` clean.

package/upgrades/side-effects/mesh-signing-key-filename-fix.md

@@ -0,0 +1,54 @@
+# Side-effects review — mesh signing-key filename fix (the SEND-side break)
+
+## What was happening (real-hardware, 2026-05-30)
+
+After the /mesh/rpc auth exemption (v1.3.104) deployed to BOTH machines, the Mac
+mini STILL showed offline on the laptop (the router). The mini→laptop presence
+pull worked (the mini's log: `recorded 1 peer(s) online: m_cc2ec651`), but the
+laptop→mini direction never fired and the mini never even RECEIVED the laptop's
+`session-status` call.
+
+Root cause: the server-boot loader for `localSigningKeyPem` — the private key the
+`MeshRpcClient` signs every outbound machine-to-machine command with — hard-coded
+the filename `signing-private.pem`. But `MachineIdentity` writes the signing key
+as `signing-key.pem` (its `SIGNING_KEY_FILE`). So a normally-created install had
+`signing-private.pem` ABSENT → `localSigningKeyPem` stayed `''` → the
+`MeshRpcClient` signed with an empty key → the send threw → the machine could NOT
+pull presence from / deliver to / transfer to any peer. It still RECEIVED fine,
+because the receive path verifies the OTHER machine's key (which it has), not its
+own. That produced the exact asymmetry observed: the mini (propagated with the
+non-canonical `signing-private.pem`) could send; the laptop (canonical
+`signing-key.pem`) could not — two filename bugs lining up.
+
+Confirmed by giving the laptop a `signing-private.pem` copy of its own key +
+restarting: the laptop immediately began recording the mini online over HTTP, and
+the pool showed both machines online.
+
+## The fix
+
+- **`src/commands/server.ts`** — the loader now reads the CANONICAL
+  `signing-key.pem` first, falling back to the legacy/propagated
+  `signing-private.pem`, so BOTH layouts load a key. (The lease transport already
+  used `idMgr.loadSigningKey()`, which reads the canonical name — only this
+  MeshRpcClient loader was on the wrong filename.)
+
+## Blast radius
+
+- **Pure fix to a boot-time read on the multi-machine path.** A single-machine
+  agent never constructs a MeshRpcClient, so it is unaffected. A machine that
+  already had `signing-private.pem` (propagated) keeps working via the fallback.
+  A machine with the canonical `signing-key.pem` (the common case) now loads its
+  key and can SEND cross-machine commands — the bug fix.
+- **No new config / route / schema / hook / skill → no migration.** Server code;
+  existing agents pick it up on the next release. This is the SEND-side companion
+  to the /mesh/rpc auth exemption (the receive-side fix) — both were needed for
+  the cross-machine pool to function over the wire.
+- **Separately, the propagation path should write the canonical `signing-key.pem`**
+  (it currently writes `signing-private.pem`); that is a propagation-side cleanup
+  tracked separately. This fix makes the loader tolerant of both regardless.
+
+## Tests
+
+- `tests/unit/mesh-signing-key-resolution.test.ts` — the loader reads the
+  canonical `signing-key.pem`, tries it BEFORE the legacy `signing-private.pem`
+  (fallback order), and the canonical name matches `MachineIdentity.SIGNING_KEY_FILE`.