instar 1.3.55 → 1.3.57

package/upgrades/side-effects/launchctl-test-hygiene.md

@@ -0,0 +1,42 @@
+# Side-Effects Review — launchctl load test-hygiene guard (MM-Bootstrap Track C follow-up)
+
+**Scope.** `src/commands/setup.ts` (new `launchctlLoadAllowed()` helper + guard
+at the 2 install-path `launchctl bootstrap` sites: installMacOSLaunchAgent +
+installFleetWatchdog), `tests/unit/launchctl-load-guard.test.ts` (new).
+
+**Problem.** The Track C unit test (merged #470) writes a LaunchAgent plist via
+`installAutoStart` to verify the Label-keyed-replace property. But
+`installMacOSLaunchAgent` does a real `launchctl bootstrap` (load) after writing
+— so the test loaded tmpdir-pointed plists into the operator's REAL launchd,
+leaving stale `ai.instar.mmtesthandoff` / `ai.instar.mmteststandby` entries
+(status 78, program gone) after the tmpdir was cleaned. Inert but real
+test-pollution of the user's launchd, discovered 2026-05-28.
+
+**Fix.** `launchctlLoadAllowed()` returns false under a test runner (vitest
+auto-sets `VITEST`) or when `INSTAR_SKIP_LAUNCHCTL_LOAD` is set. The two
+install-path bootout+bootstrap blocks are wrapped in it. The plist file is still
+written/removed; only the LIVE load is gated — so the unit-under-test (plist
+content) is unaffected, and production (neither flag set) loads normally.
+
+**Side-effects review.**
+- **No production behavior change** — in a normal environment neither VITEST nor
+  INSTAR_SKIP_LAUNCHCTL_LOAD is set, so `launchctlLoadAllowed()` is true and the
+  load happens exactly as before.
+- **Tests no longer pollute real launchd** — verified: re-running the Track C
+  test creates NO mmtesthandoff/mmteststandby entries (the guard skipped the
+  load), and the test still passes (it asserts plist CONTENT, not live load).
+- **uninstallAutoStart's bootout is intentionally NOT gated** — that's cleanup
+  (removing a real entry), correct to keep even in tests; only the install-path
+  LOAD is the pollution vector.
+- **Minimal surface** — one helper + two wraps; no new dependency.
+
+**Test coverage.** Unit `tests/unit/launchctl-load-guard.test.ts` (3): false
+under VITEST, false under INSTAR_SKIP_LAUNCHCTL_LOAD, true when neither set
+(production). Plus the existing Track C test now verifiably runs without
+pollution.
+
+**Migration parity.** Server source (setup.ts) — existing agents pick up on
+auto-update. No agent-installed-file change; production load behavior unchanged.
+
+**Rollback.** Revert. Tests would resume polluting real launchd (inert stale
+entries). No production impact either way.

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

package/upgrades/1.3.55.md

@@ -1,38 +0,0 @@
-# Instar Upgrade Guide — NEXT
-
-<!-- bump: patch -->
-
-## What Changed
-
-**Post-publish smoke gate (publish-pipeline regression insurance).** A new step
-after `npm publish` clean-installs the just-published version into a throwaway
-prefix and runs `instar --version`, asserting the tarball actually installs and
-reports the right version. If the publish pipeline ever ships a tarball missing
-its compiled output, this catches it within minutes of release instead of when a
-fresh install fails in the wild. (Track A was re-scoped from a "fix" to this gate:
-the original "empty dist" scare was self-inflicted, not a real publish bug.)
-
-## What to Tell Your User
-
-- Internal release-pipeline hardening: after I publish a new version, CI now
-  immediately does a clean install of it and checks it runs, so a broken release
-  can't slip out unnoticed. Nothing changes for you — it's a safety net on my own
-  shipping process.
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Post-publish smoke gate | Automatic in the publish workflow — clean-installs the just-published version + asserts `instar --version`. |
-
-## Evidence
-
-**Re-scoped to regression insurance (the original premise was a self-inflicted
-artifact, not a bug).** `scripts/post-publish-smoke.mjs` waits for npm
-propagation, clean-installs into a throwaway prefix, asserts `dist/cli.js` exists
-+ `--version` matches. Unit test `tests/unit/post-publish-smoke.test.ts` (4)
-covers the pure version-match logic incl the 1.3.5-vs-1.3.55 substring trap.
-`publish.yml` validates as YAML; the step mirrors the existing publish steps'
-structure + gating. Side-effects review:
-`upgrades/side-effects/publish-completeness-smoke-gate.md`. Spec: Track A of
-`docs/specs/MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS-SPEC.md`.