instar 1.3.56 → 1.3.58

package/upgrades/1.3.57.md

@@ -0,0 +1,49 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**1. Mentor cycle round-trip — final fixes (verified live end-to-end).** Three bugs that only surfaced when the full Echo↔Codey round-trip ran on real servers:
+
+1. **`mentor.menteeAgentName` config.** The mentor derived the mentee's agent name as `instar-${menteeFramework}` (e.g. `instar-codex-cli`), but the mentee registers under its real name (`instar-codey`). The mismatch broke same-machine peer lookup AND the reply allowlist. New optional `mentor.menteeAgentName` (defaults to `instar-${menteeFramework}`) carries the real registry name.
+2. **botId string coercion.** `mentor.menteeBotId` is often stored as a JSON number, but the a2a marker's `senderBotId` is always a string. The allowlist compares with `===`, so a number/string mismatch silently dropped every reply as `agent-marker-unknown`. All botId allowlist entries are now `String()`-coerced.
+3. **`senderBotId` = sender's own bot id.** The unified transport sent the *recipient's* bot id as the inbox `senderBotId`; the recipient's allowlist check (`knownAgents[from].botId === senderBotId`) therefore always failed. It now sends the *sender's* own bot id (`ownPrimaryBotId()` for replies, the mentor bot id for sends).
+
+With these, the mentor cycle round-trips live: a mentor prompt reaches the mentee, the mentee spawns a session + replies, and the reply lands in the mentor's `mentor-replies.jsonl`.
+
+**2. Threadline identity-discovery unification** (spec `docs/specs/threadline-identity-discovery-unification.md`, approved). Fixes a fleet-wide bug where an agent advertised a Threadline identity its own relay does not answer to — so peers who discovered it got a dead address and their messages silently vanished.
+
+Discovery (`agent-info.json`) and `/threadline/health` now advertise the **routing fingerprint** — the address the relay actually registers with — plus a `publicKey`/`identityPub` set to the SAME canonical `identity.json` key, so the two are internally consistent (`fingerprint === computeFingerprint(publicKey)`). Both are resolved via `IdentityManager.get()`, the exact read-only call the relay client uses, so discovery and routing can never re-diverge.
+
+## What to Tell Your User
+
+- The cross-agent mentor cycle now works fully end-to-end on the same machine — verified with a real round-trip. These were the last three wiring bugs (an agent-name assumption, a number-vs-string comparison, and a sender-identity mixup). No config changes required unless your mentee's registry name differs from the default (instar plus the framework name), in which case set the mentee agent name in config.
+- If another agent's messages to me were vanishing (their side said "sent" but nothing arrived), the Threadline fix addresses it: I was handing out an address my relay doesn't listen on. Now I publish the right one everywhere, and existing agents are repaired automatically on the next update/restart — no action needed.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| `mentor.menteeAgentName` | Set in `.instar/config.json` when the mentee's agent-registry name differs from `instar-<menteeFramework>` (e.g. `instar-codey`). Defaults to the framework-derived name. |
+| Robust botId matching | botId allowlist entries are string-coerced; `senderBotId` is the sender's own bot id. No action needed — fixes silent reply drops. |
+| `fingerprint` field in `/threadline/health` + `agent-info.json` | `curl localhost:PORT/threadline/health` → `fingerprint` is the routable relay address |
+| Threadline fleet repair migrator | `migrateThreadlineAgentInfoIdentity` runs on update; rewrites a diverged `agent-info.json` to the canonical consistent pair (no-op when already aligned or no routing identity) |
+
+## Behavior Notes (Threadline)
+
+- **No fabrication:** an agent with no resolvable routing identity (none on disk, or a locked-encrypted `identity.json`) now OMITS `fingerprint`/`publicKey` from discovery instead of inventing a dead address. It becomes relay-discoverable once it has a routing identity (self-heals on the next boot).
+- **Safe encoding/consumer story:** `publicKey` stays hex and is a valid 32-byte Ed25519 key; `/threadline/health.identityPub` switches to the canonical key only when one resolves. The E2E handshake exchanges keys inline (does not read these fields) and `verifyAgent` does no real crypto challenge, so the switch is safe.
+
+## Evidence
+
+- **Mentor cycle:** extended `mentor-reply-via-inbox` E2E with a second case proving the menteeAgentName override + numeric-configured botId (string senderBotId) routes + persists. Both cases green; all prior mentor/mentee/inbox tests green. **Live-verified**: full Echo→Codey→Echo round-trip persisted to `mentor-replies.jsonl`. Side-effects: `upgrades/side-effects/mentee-agent-name-and-botid-coercion.md`.
+- **Threadline — wiring (load-bearing):** boot the Threadline stack with a seeded canonical identity → `agent-info.json.fingerprint` equals `IdentityManager.getOrCreate().fingerprint` (the relay's registration source). `tests/e2e/threadline/identity-discovery-wiring.test.ts`.
+- **Threadline — integration:** `/threadline/health` returns a non-empty `identityPub` + a `fingerprint` equal to the relay-registration fingerprint, internally consistent. `tests/integration/threadline/identity-discovery-health.test.ts`.
+- **Threadline — unit (both-sides):** identity present → consistent pair advertised; no/locked identity → both omitted; orphan `identity-keys.json` present → canonical advertised, never the orphan hex. `ThreadlineBootstrap.test.ts`, `ThreadlineEndpoints.test.ts`.
+- **Threadline — migrator:** diverged → repaired; aligned → no-op; no-identity → no-op (no fabrication); idempotent. `tests/unit/PostUpdateMigrator-threadlineAgentInfoIdentity.test.ts`. Verified end-to-end via test-as-self against the built dist (positive + no-identity boundary).
+
+## Out of Scope (Threadline — tracked separately)
+
+- Multi-machine same-fingerprint advertisement coordination (cross-machine seamlessness spec). This fix sets the `machine` field and is neutral for multi-machine.
+- Retiring the orphan `identity-keys.json` / collapsing the keypairs. This fix stops *advertising* the orphan; deleting it touches the handshake layer and needs its own spec.

package/upgrades/1.3.58.md

@@ -0,0 +1,47 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Mentor cycle: the two remaining smoothness issues fixed.**
+
+1. **Robust reply capture (no more empty / raw-JSON replies).** The mentee
+   role-handler captured the tmux pane after the session completed — racing
+   the reaper (→ empty reply) and yielding raw codex stream JSON. It now reads
+   the session's persisted transcript: codex → the rollout's
+   `task_complete.last_agent_message` (clean prose), claude → the JSONL
+   transcript's last assistant text. The tmux capture remains a fallback when
+   no transcript is found. New `SessionReplyExtractor` module (pure, unit-
+   tested) + `extractMenteeReplyFromTranscript` wiring.
+
+2. **`isMenteeBusy` is remote-aware.** It checked Echo's LOCAL
+   `sessionManager.listRunningSessions()` — always non-empty, so every mentor
+   tick was wrongly blocked as "busy" (the mentee is a separate remote agent;
+   Echo's local sessions say nothing about it). It now gates on the
+   `OutstandingPromptTracker` — busy iff a prior mentor prompt to this mentee
+   is still unanswered. That's the honest per-mentee signal and the same
+   anti-ping-pong invariant, so real ticks now fire when the mentee is idle.
+
+## What to Tell Your User
+
+The cross-agent mentor cycle now runs cleanly: replies come back as readable
+prose (not empty, not raw stream JSON), and the scheduled mentor tick actually
+fires when the mentee is free (it was previously always self-blocked). No
+config changes.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Transcript-based mentee reply capture | Automatic — the mentee reply is read from the session transcript (codex rollout / claude JSONL), clean prose, robust to the reap race. |
+| Remote-aware mentor safe-window | Automatic — `isMenteeBusy` gates on the outstanding-prompt tracker, so `/mentor/tick` runs when no prior prompt is in-flight. |
+
+## Evidence
+
+10 new unit tests for `SessionReplyExtractor` (codex task_complete / agent_message /
+response_item fallbacks + claude assistant extraction + malformed tolerance),
+all green. mentor-runner + mentor/mentee/inbox suites still green; `tsc
+--noEmit` clean. Live round-trip re-verification (tick-driven, clean prose)
+runs post-release. Side-effects:
+`upgrades/side-effects/mentor-cycle-smoothness.md`.

package/upgrades/side-effects/mentee-agent-name-and-botid-coercion.md

@@ -0,0 +1,55 @@
+# Side-Effects Review — menteeAgentName + botId coercion + senderBotId fix
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Recipient side. Final
+fixes closing the live round-trip (the reply leg landed in #469; these are the
+three remaining wiring bugs found by running it end-to-end).
+
+**Change:** `src/scheduler/MentorOnboardingRunner.ts` (+1 optional config
+field) + `src/server/AgentServer.ts` (menteeAgentName usage at 3 derivation
+sites, botId String-coercion at 3 allowlist sites, senderBotId=sender's-own
+via new `ownPrimaryBotId()` helper) + extended E2E test.
+
+## What changed
+1. `MentorConfig.menteeAgentName?: string` — the mentee's real registry name.
+   Used in `deliverToMentee`, `installMentorMessageHook` (mentor side), and
+   `installMentorReceiverHook`, each falling back to `instar-${menteeFramework}`.
+2. botId `String()`-coercion at every knownAgents construction (mentor side,
+   mentee side, receiver hook) — config may store a JSON number; the marker
+   senderBotId is always a string; the allowlist uses `===`.
+3. `deliverA2aMessage` now takes `fromBotId` (sender's own bot id) and sends
+   it as the inbox `senderBotId`. `ownPrimaryBotId()` derives this agent's bot
+   id from its messaging config token. Replies pass `ownPrimaryBotId()`; sends
+   pass the mentor bot id.
+
+## The seven questions
+1. **Over-block.** N/A — these LOOSEN an over-strict (buggy) comparison that
+   was dropping legitimate replies. Coercion only makes a number match its
+   string form; it does not widen the allowlist to new agents.
+2. **Under-block.** The allowlist still requires an exact (coerced) botId
+   match + known agent name. Spoof defense intact — a wrong botId still drops.
+3. **Level-of-abstraction fit.** Small, local fixes at the exact sites; one
+   tiny helper (`ownPrimaryBotId`). No new infrastructure.
+4. **Signal vs authority.** Unchanged — allowlist still decides route/drop.
+5. **Interactions.** `menteeAgentName` defaults preserve back-compat for any
+   agent whose registry name already equals `instar-<framework>`. Coercion is
+   idempotent on already-string values.
+6. **External surfaces.** One new optional config key (`mentor.menteeAgentName`).
+   No new routes.
+7. **Rollback cost.** Trivial — revert restores framework-derived names + the
+   number/string comparison (re-introducing the silent reply drop).
+
+## Testing
+Extended `mentor-reply-via-inbox` E2E (now 2 cases): the original
+(framework-derived name, string botId) + the new regression (menteeAgentName
+override, numeric-configured botId, string senderBotId) — both route + persist.
+All prior mentor/mentee/inbox tests green. tsc clean.
+
+**Live verification (test-as-self):** the worktree build was shadow-deployed to
+the live Echo + Codey pair; a real mentor prompt round-tripped — Codey spawned
+a mentee session, replied via /a2a/inbox, and Echo persisted the reply to
+mentor-replies.jsonl (corr=FULL-…, from=instar-codey, transport=a2a-inbox-local).
+
+## Migration parity
+`mentor.menteeAgentName` is optional with a back-compat default — no migration
+needed. The botId coercion + senderBotId fix are pure code (no config/state
+change). No PostUpdateMigrator change.

package/upgrades/side-effects/mentor-cycle-smoothness.md

@@ -0,0 +1,48 @@
+# Side-Effects Review — mentor cycle smoothness (capture + busy-gate)
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Recipient side. The two
+fast-follows from the live round-trip: reply-capture reliability + the
+remote-mentee safe-window.
+
+**Change:** new `src/monitoring/SessionReplyExtractor.ts` (pure extractors) +
+`src/server/AgentServer.ts` (`extractMenteeReplyFromTranscript` helper, wired
+into the mentee handler as transcript-first/tmux-fallback; `isMenteeBusy`
+gates on OutstandingPromptTracker) + unit tests.
+
+## What changed
+1. `extractCodexFinalMessage` / `extractClaudeFinalMessage` — pure, tolerant
+   parsers returning the final assistant prose (null when absent).
+2. `extractMenteeReplyFromTranscript(session, spawnTs)` — codex: newest rollout
+   written ≥ spawn → task_complete.last_agent_message; claude: the
+   `<claudeSessionId>.jsonl` under ~/.claude/projects → last assistant text.
+3. Mentee handler: after the bounded-wait, prefer the transcript reply; keep
+   the existing capture-while-alive tmux read as the only fallback.
+4. `isMenteeBusy`: `!getOrCreateMentorOutstanding().canSendTo(menteeAgent).ok`
+   instead of Echo's local session count.
+
+## The seven questions
+1. **Over-block.** isMenteeBusy now blocks LESS (only when a real prompt is
+   outstanding) — it was over-blocking before (always busy). Correct direction;
+   the anti-ping-pong invariant is preserved (one outstanding prompt per mentee).
+2. **Under-block.** The outstanding-prompt gate still prevents concurrent
+   prompts to the same mentee. Transcript reading is read-only (no new writes).
+3. **Level-of-abstraction fit.** Extractors are pure + isolated; the helper
+   reuses findRecentRolloutFiles (existing). isMenteeBusy reuses the existing
+   tracker. No new infrastructure.
+4. **Signal vs authority.** Extractors are pure signal; the handler decides.
+   isMenteeBusy is a gate input to the existing safe-window decision.
+5. **Interactions.** Reads ~/.codex/sessions + ~/.claude/projects (read-only).
+   Reuses OutstandingPromptTracker (shared with deliverToMentee — consistent
+   semantics). No new shared mutable state.
+6. **External surfaces.** None new. mentor-replies.jsonl now carries clean
+   prose instead of stream JSON (content-quality change, same schema).
+7. **Rollback cost.** Trivial — revert restores tmux-only capture + the local
+   session-count busy check.
+
+## Testing
+10 new unit tests (SessionReplyExtractor) green; mentor-runner + mentor/mentee/
+inbox suites green; tsc clean. Live tick-driven round-trip with clean-prose
+capture verified post-release (the autonomous run's completion criterion).
+
+## Migration parity
+No config keys, no state schema change. Pure code. No PostUpdateMigrator change.

package/upgrades/side-effects/test-as-self-skill-demote.md

@@ -0,0 +1,38 @@
+# Side-Effects Review — test-as-self SKILL Part 2.1 demote + migrator (Track F follow-up)
+
+**Scope.** `.claude/skills/test-as-self/SKILL.md` (lead with the one-button
+command, demote the manual recipe to fallback), `src/core/PostUpdateMigrator.ts`
+(`migrateTestAsSelfSkill` + registration), `tests/unit/migrate-test-as-self-skill.test.ts`.
+
+**What + why.** Track F shipped the `instar test-as-self` command but left the
+SKILL.md as the v1 manual runbook (deferred, tracked). This closes that loop:
+the SKILL now leads with "## The one-button path (Part 2.1 — use this first)"
+(the command), with the manual recipe demoted to fallback — so an agent reading
+the skill reaches for the command first. Plus a PostUpdateMigrator method so
+EXISTING agents' on-disk SKILL.md gets the update (installBuiltinSkills is
+install-if-missing, so a dedicated migration is the only path per the Migration
+Parity Standard).
+
+**Side-effects review.**
+- **Content-only skill change** — no behavior change; the command itself shipped
+  in Track F (#472). This just makes it discoverable in the skill surface.
+- **Migration is conservative + idempotent** — re-copies the bundled SKILL only
+  when the installed copy LACKS the Part 2.1 marker AND still matches the stock
+  fingerprint (`Throwaway-Deploy Harness` + `verify.mjs`). A customized skill is
+  left untouched (recorded in result.skipped); an already-updated one is a no-op;
+  a not-installed one is a no-op. Mirrors the proven migrateBuildSkillMethodology
+  pattern exactly.
+- **No data/secret impact** — pure doc/skill content.
+
+**Test coverage.** Unit `tests/unit/migrate-test-as-self-skill.test.ts` (4):
+stock-v1 → updated (marker present, result.upgraded set); idempotent (already-
+marked → unchanged, no upgrade); customized → untouched (result.skipped);
+not-installed → no-op (no error). All green; tsc clean. The test also implicitly
+verifies the bundled SKILL.md carries the new marker.
+
+**Migration parity.** This IS the migration-parity fix for Track F's SKILL
+update. New agents get the new SKILL via installBuiltinSkills; existing agents
+get it via `migrateTestAsSelfSkill` on update.
+
+**Rollback.** Revert. The SKILL reverts to the v1 manual-first runbook; the
+command still works (it's independent). No data change.

package/upgrades/side-effects/threadline-identity-discovery-unification.md

@@ -0,0 +1,100 @@
+# Side-Effects Review — Threadline Identity-Discovery Unification
+
+**Slug:** `threadline-identity-discovery-unification`
+**Date:** 2026-05-28
+**Author:** Echo (instar developer)
+**Spec:** `docs/specs/threadline-identity-discovery-unification.md` (converged iter 2, approved)
+
+## Summary of the change
+
+Discovery was advertising an identity the agent's own relay does not answer to.
+`announcePresence` wrote `agent-info.json.publicKey` from the orphan
+`threadline/identity-keys.json` hex key, and `/threadline/health` reported
+`identityPub` from the HandshakeManager key (empty on some agents) — while the
+relay client registers (and routes) by the canonical `identity.json`
+fingerprint. A peer who discovered the agent got a non-routable address, so
+their messages vanished (their side `sent=true`, no "Accepted message from …"
+on the receiver). Fleet-wide for any agent whose canonical identity was
+generated independently of its legacy keys.
+
+The fix advertises the **routing identity** everywhere, internally consistent:
+`agent-info.json` and `/threadline/health` now publish a `fingerprint`
+(routable relay address) plus a `publicKey`/`identityPub` set to the SAME
+canonical key, sourced from `IdentityManager.get()` — the exact read-only API
+the relay client uses, so the two can never re-diverge.
+
+**Files changed (source):**
+- `src/threadline/AgentDiscovery.ts` — `fingerprint` field on `AgentInfoFile`,
+  `ThreadlineAgentInfo`, `HealthResponse`; `announcePresence` accepts +
+  persists it; `pingThreadlineHealth`/`verifyAgent` propagate it.
+- `src/threadline/ThreadlineBootstrap.ts` — resolve `IdentityManager.get()` up
+  front; advertise canonical `publicKey`(hex)+`fingerprint`+`machine`; omit both
+  when `get()` is null (no fabrication).
+- `src/threadline/ThreadlineEndpoints.ts` — `/threadline/health` sources
+  `identityPub`+`fingerprint` from `IdentityManager.get()`; `stateDir` added to
+  config; falls back to the handshake key + omits fingerprint when no routing
+  identity resolves.
+- `src/server/routes.ts` — pass `stateDir` to `createThreadlineRoutes`.
+- `src/core/PostUpdateMigrator.ts` — `migrateThreadlineAgentInfoIdentity`
+  (belt-and-suspenders fleet repair) + `migrateClaudeMd` routing-fingerprint
+  guidance section.
+- `src/scaffold/templates.ts` — CLAUDE.md template "What address reaches me"
+  section (Agent Awareness).
+- `src/data/builtin-manifest.json` — regenerated by the build (template hashes).
+
+**Files changed (tests):** `ThreadlineBootstrap.test.ts`,
+`ThreadlineEndpoints.test.ts` (+3 new: migrator unit, health integration,
+bootstrap wiring e2e).
+
+**Drive-by (unrelated, green-keeping):** `src/commands/test-as-self.ts` line 60
+— `new URL(import.meta.url).pathname` → `fileURLToPath(import.meta.url)`. This
+is the URL-pathname-path-encoding pattern (breaks when the project path
+contains spaces) that the pre-push gate (`scripts/pre-push-gate.js`) flags; it
+was introduced into `test-as-self.ts` by an earlier merge and the pre-push gate
+blocks any push until it is fixed (the check is pre-push-only, not in CI, which
+is why it landed). One-line fix to the documented-correct pattern; no behavior
+change.
+
+## Blast radius / consumers
+
+- **`agent-info.json.publicKey` encoding** is unchanged (hex) and now sourced
+  from the canonical key. Consumers (`verifyAgent` does `Buffer.from(.., 'hex')`
+  + 32-byte length check) still work; the key is a valid 32-byte Ed25519 key.
+- **`/threadline/health.identityPub`** switches from the handshake key to the
+  canonical routing key WHEN one resolves. Safe: `verifyAgent` does not perform
+  a real cryptographic challenge (nonce generated, never exchanged), and the E2E
+  handshake exchanges keys inline — it does not read `agent-info.json` or the
+  health `identityPub`. Verified by reading `ThreadlineEndpoints.ts` handshake
+  paths + `AgentDiscovery.verifyAgent`.
+- **No-fabrication boundary:** a relay-disabled / no-identity / locked-encrypted
+  agent now OMITS `fingerprint`+`publicKey` instead of advertising a key for an
+  identity on no relay. This is a behavior change for brand-new agents on their
+  very first announce (before the relay client creates an identity) — correct
+  per spec (not relay-discoverable until a routing identity exists), self-heals
+  on the next boot once the identity is created.
+- **Migrator** only rewrites `agent-info.json` when `get()` resolves AND the
+  file is misaligned; no-ops otherwise (idempotent, atomic write, never
+  fabricates).
+
+## Migration parity
+
+Existing agents: the in-`announcePresence` rewrite self-heals on the
+post-update server restart; `migrateThreadlineAgentInfoIdentity` closes the
+narrow update-without-restart window; `migrateClaudeMd` adds the guidance for
+agents whose CLAUDE.md predates this. New agents get all of it via `init` +
+the template.
+
+## Out of scope (tracked, not deferred)
+
+- Multi-machine same-fingerprint advertisement coordination →
+  `project_cross_machine_seamlessness_spec`. This fix sets the `machine` field
+  (attributable) and is neutral for multi-machine.
+- Retiring the orphan `identity-keys.json` / collapsing the 3–4 keypairs →
+  `bug_threadline_identity_divergence_discovery`. This fix stops *advertising*
+  the orphan; deleting it touches the handshake layer and needs its own spec.
+
+## Risk
+
+Low. Additive at the field level; `agent-info.json` is regenerated on every
+boot regardless. Reverting removes the field + migrator with no data loss. All
+three test tiers + wiring + both-sides green; full `test:push` suite green.