instar 1.3.104 → 1.3.106

package/upgrades/1.3.105.md

@@ -0,0 +1,64 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**The Framework-Onboarding mentor now reports WHY a tick failed, and its Stage-A
+step is more resilient.** The mentor's Stage-A step spawns a tiny tool-less
+session to compose the next coaching message, then captures it. When that spawn
+failed (common on a busy multi-agent box — session-cap pressure / load), the
+whole tick collapsed to an opaque `stage-a-failed` with the real cause thrown
+away, so it was undiagnosable from `GET /mentor/status`. Now: the real error is
+surfaced into `lastResult.error`, and the Stage-A compose-session spawn retries
+once with a short backoff before failing with a clear, specific message.
+
+**Multi-machine: the SEND side of the cross-machine command channel now works on
+a normally-created machine.** The private per-machine key used to sign every
+machine-to-machine command was being loaded from the wrong filename
+(`signing-private.pem`), but a normally-created machine stores it as
+`signing-key.pem`. So a normal machine signed its outbound commands with an empty
+key and the send silently failed — it could receive from peers but never call out
+to them (check a peer's presence, hand off a conversation, move one). The loader
+now reads the canonical filename, falling back to the legacy one. This is the
+send-side companion to the recent command-channel auth fix; together they make
+the cross-machine pool actually work over the network. (Found on real hardware:
+the laptop couldn't see the mini until its signing key loaded.)
+
+## What to Tell Your User
+
+Only relevant if you run the (off-by-default) Framework-Onboarding mentor. It now
+recovers from a transient compose-session spawn failure, and when it does fail it
+tells you exactly why (visible on the mentor status page) instead of an
+unexplained "stage-a-failed."
+
+If you run across two machines: this release fixes the last piece that kept a
+normally-created machine from being able to reach its peers — a second machine
+will now correctly show as online and be eligible to receive conversations, and
+moving a conversation between machines works. Both machines need to update.
+
+## Summary of New Capabilities
+
+- `GET /mentor/status` → `lastResult.error` now carries the real Stage-A failure
+  cause (`MentorTickResult.error`), instead of swallowing it.
+- `spawnStageA` retries the compose-session spawn once (transient resilience) and
+  throws a clear `stage-a-spawn-failed: … — <cause>` on persistent failure.
+- The MeshRpcClient signing-key loader reads the canonical `signing-key.pem`
+  (falling back to legacy `signing-private.pem`), so a normally-created machine
+  can sign — and therefore SEND — cross-machine commands.
+
+## Evidence
+
+- `tests/unit/MentorOnboardingRunner.test.ts` (+1): a `spawnStageA` that throws
+  now yields `lastResult = {ran:false, reason:'stage-a-failed', error:<msg>}` —
+  asserts the cause is surfaced (was swallowed by a bare catch in
+  `runMentorTick`). Full mentor/stage suite (113 tests / 9 files) green;
+  `tsc --noEmit` clean.
+- `tests/unit/mesh-signing-key-resolution.test.ts` — the loader reads the
+  canonical `signing-key.pem`, tries it before the legacy `signing-private.pem`,
+  and the canonical name matches `MachineIdentity.SIGNING_KEY_FILE`.
+- Found on real hardware (laptop + mini): the laptop's puller recorded the mini
+  online over the signed HTTP channel only after its signing key loaded; before,
+  it signed with an empty key and the send threw.
+- Side-effects: `upgrades/side-effects/mentor-stage-a-robustness.md`,
+  `upgrades/side-effects/mesh-signing-key-filename-fix.md`.

package/upgrades/1.3.106.md

@@ -0,0 +1,39 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Fixed the root cause of the Framework-Onboarding mentor's Stage-A failures: the
+compose prompt grew past tmux's command-line limit.** Stage-A spawns a session to
+compose the next coaching message, passing the prompt — which embeds the whole
+growing mentor↔mentee conversation — as a `tmux new-session` command-line
+argument. tmux has a command-length limit (~12-16KB); once the accumulated
+history crossed it, `tmux new-session` failed with "command too long", so the
+step failed and the mentee got nothing (it worked early on, then broke as history
+piled up). The conversation history fed into the Stage-A prompt is now bounded to
+the most-recent ~6KB (with an explicit "older conversation elided" marker), so the
+spawn stays under tmux's limit no matter how long the mentorship runs.
+
+## What to Tell Your User
+
+Only relevant if you run the (off-by-default) Framework-Onboarding mentor. Its
+Stage-A step is now reliable for long-running mentorships — the prompt can't grow
+past the limit that was making it fail. No behaviour change for short
+conversations.
+
+## Summary of New Capabilities
+
+- `buildStageAContext` bounds the conversation history at 6000 chars (keeps the
+  most-recent exchanges + a marker), keeping the Stage-A prompt under tmux's
+  command-line limit — fixes the `stage-a-failed` root cause.
+
+## Evidence
+
+- `tests/unit/MentorStageA.test.ts` (+1): an ~80KB history produces a prompt
+  under 12KB that keeps the most-recent exchange, carries the elision marker, and
+  preserves the prompt structure. Full mentor/stage suite (114 tests / 9 files)
+  green; `tsc` + `npm run lint` clean.
+- Cold tmux repro: a 120KB argument to `tmux new-session` fails with "command too
+  long"; 12KB passes — confirming the 6KB history cap is safely below the limit.
+- Side-effects: `upgrades/side-effects/mentor-stage-a-prompt-bound.md`.

package/upgrades/side-effects/mentor-stage-a-prompt-bound.md

@@ -0,0 +1,55 @@
+# Side-effects review — Mentor Stage-A: bound the compose prompt
+
+**Spec:** `docs/specs/MENTOR-STAGE-A-PROMPT-BOUND-SPEC.md`
+**Change:** `src/monitoring/MentorStageA.ts` (`buildStageAContext`) + unit test
+**Class:** mentor reliability fix (root cause of `stage-a-failed`).
+
+## What changed
+
+`buildStageAContext` now caps `surface.threadlineHistory` at `MAX_HISTORY_CHARS =
+6000`, keeping the most-recent tail + an explicit `older conversation elided`
+marker, so the assembled Stage-A prompt can't exceed tmux's `new-session`
+command-line limit (~12-16KB) — the confirmed cause of the spawn failure.
+
+## Blast radius
+
+- **`buildStageAContext` callers:** only `runMentorTick` (Stage-A). The function
+  signature/output shape is unchanged (still returns the prompt string); only the
+  history portion is bounded when it exceeds 6000 chars.
+- **Mentor behaviour:** unchanged for short histories (the bound only engages
+  above 6000 chars). For long histories, the prompt now contains the recent
+  exchanges + a marker instead of the full transcript — the mentor still has the
+  agenda + recent state to decide the next action.
+- **Two-hats isolation / leak detection / agenda logic:** untouched.
+- **Public API / DB schema / config / other spawns:** none changed. Regular
+  (non-mentor) session spawns are unaffected (their prompts are small and were
+  never the growth vector).
+
+## What could break (and why it doesn't)
+
+- **Mentor lacks older context?** By design — the recent 6KB + agenda + status
+  carry the "what's next" decision; older middle history is least relevant.
+- **A single huge recent message?** The hard char cap bounds the history block
+  regardless of message boundaries.
+- **Leak detector seeing a truncated transcript?** It runs on the Stage-A
+  *output* transcript, not on this input prompt — unaffected.
+
+## Security
+
+No new external input / network / auth / fs surface. Pure in-memory string bound.
+
+## Migration parity
+
+Server-internal monitoring 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/MentorStageA.test.ts` (+1): an ~80KB history → prompt < 12KB, keeps
+the most-recent exchange, carries the elision marker, preserves structure. Full
+mentor/stage suite (114 tests / 9 files) green; `tsc` + `npm run lint` clean.
+Cold tmux repro confirmed the limit (120KB → "command too long"; 12KB passes).

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`.