instar 1.3.249 → 1.3.251

package/upgrades/side-effects/instar-dev-build-location-regrounding.md

@@ -0,0 +1,85 @@
+# Side-Effects Review — instar-dev build-location re-grounding
+
+**Version / slug:** `instar-dev-build-location-regrounding`
+**Date:** `2026-06-04`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change hardens the instar-dev workflow against a mentor-onboarding failure mode: a respawned agent built a fleet PR from a stale agent-home checkout instead of current `JKHeadley/instar` main. Phase 2 of the instar-dev skill now requires an explicit build-location re-grounding plan item before code edits: confirm a fresh current-main worktree, verify the remote, and verify the package version. If the agent uses a fresh clone fallback instead of `instar worktree create`, it must immediately set the local agent git identity so commits do not fall back to the operator's global git config. PostUpdateMigrator backfills existing deployed instar-dev skills by content-sniffing for the new marker and replacing only stock skill copies; customized skill text is left untouched.
+
+## Decision-point inventory
+
+- `/instar-dev` Phase 2 planning checklist — modify — adds a required self-verification step before build execution, including agent git identity setup for fresh-clone fallbacks.
+- `PostUpdateMigrator` built-in skill migration — modify — updates deployed stock instar-dev skill files during agent update.
+- Commit/push gates — pass-through — unchanged; they continue to enforce side-effects/release metadata after this workflow step has grounded the checkout.
+
+---
+
+## 1. Over-block
+
+The skill now requires a planning statement even for small instar-dev changes. That can feel redundant when the agent is already visibly in a correct worktree, but it is intentionally cheap and does not block via code; the enforcement is procedural text plus review artifacts. The migrator only overwrites installed instar-dev skill files that still match the stock fingerprint, so a customized local workflow is not clobbered.
+
+---
+
+## 2. Under-block
+
+This does not make a hard shell gate that rejects stale checkouts or misattributed git identity. An agent could still ignore the skill text or lie in the plan, but the expected workflow now requires the check at the right point, and the plan/review trail makes omissions visible. A future stronger gate could validate branch ancestry and local git identity automatically, but this PR focuses on the requested structural skill and migration layer.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The change belongs in Phase 2 because that is the last explicit planning checkpoint before `/build` starts edits. It also belongs in PostUpdateMigrator because the instar-dev skill is an agent-installed built-in file; updating only the package copy would leave existing agents on stale instructions.
+
+---
+
+## 4. Signal vs authority compliance
+
+- [x] No — this change produces a planning requirement and migration update, not a brittle block/allow authority.
+
+No new runtime authority is introduced. The skill text creates a required human/agent-visible checkpoint. PostUpdateMigrator makes the checkpoint available to existing agents but does not make build-location decisions.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** The new checklist item complements the existing worktree convention and pre-commit gates. It does not replace them.
+- **Double-fire:** Fresh installs receive the updated bundled skill; existing installs receive the same text once through the migrator. The marker makes repeated runs no-op.
+- **Races:** The migrator performs a single local file write during update. If the file is already customized or already current, it skips.
+- **Feedback loops:** The change reduces the chance of stale-repo fixes generating follow-up CI/PR cleanup loops.
+
+---
+
+## 6. External surfaces
+
+Existing dev agents will see updated instar-dev skill text after update if their installed copy is stock. This is intentionally fleet-visible because the bug came from a respawned development agent. End users do not invoke instar-dev; the surface is limited to infrastructure-development agents and their installed skill files.
+
+---
+
+## 7. Rollback cost
+
+Rollback is a normal code revert. Agents that already received the updated skill text would keep a harmless extra planning checklist item until a later migration rewrites it. No persistent database migration is involved.
+
+---
+
+## Conclusion
+
+The review confirms the right fix layer is the workflow body plus migration parity, not another ad hoc reminder in a transcript. The remaining gap is deliberate: this PR does not add an automatic stale-checkout or git-identity blocker. It makes the grounding step required and fleet-distributed, with tests covering update, idempotency, customization preservation, and missing-skill no-op behavior.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required
+**Independent read of the artifact:** not required
+
+This changes a dev skill and migration path but does not alter session lifecycle, messaging gates, sentinels, or runtime block/allow logic.
+
+---
+
+## Evidence pointers
+
+- Focused PostUpdateMigrator built-in skill migration tests passed.
+- TypeScript typecheck passed.

package/upgrades/side-effects/mm-self-nickname.md

@@ -0,0 +1,23 @@
+# Self-Nickname Convergence — Plain-English Overview
+
+> One line: a machine now learns its OWN user-facing nickname from its peers, so "move it back to <this machine>" finally works.
+
+## The problem in one breath
+
+We shipped placement/transfer robustness, but live-testing on the real laptop+mini pair exposed that the fix was incomplete: the laptop couldn't resolve its OWN name "Laptop". Root cause — `updateNickname` (the dashboard rename) is local-only, so a rename applied on a peer's registry never reached the owning machine. The laptop's own capacity entry was `nickname=None` while peers correctly saw "Laptop". The relocation check runs on the holder (laptop), so it couldn't match "Laptop" → "move it back to the laptop" silently failed.
+
+## What this adds
+
+- **`SelfNicknameResolver` (pure)** — resolves this machine's own nickname: local capacity view → any PEER's view that names it (the drift backstop) → deterministic derive. Unit-tested incl. the exact asymmetry (self absent locally, present in a peer view).
+- **Self-nickname convergence task (server)** — periodically (and at boot), if the local self-entry has no nickname, it fetches an online peer's `/pool`, finds what the peer calls this machine, and persists it via `updateNickname`. This makes `getCapacities()` SYMMETRIC, so the recognizer, the transfer route, and `/pool` all resolve self. No-ops once known.
+- **Transfer route** now resolves the self-nickname via the resolver (was caps-only).
+
+## The safeguards
+
+- **Best-effort, never blocks** — convergence catches all errors (annotated `@silent-fallback-ok`); a failed peer fetch just retries on the timer.
+- **No mis-routing** — adoption only happens when the local nickname is missing and a peer authoritatively names this machineId; `updateNickname` still enforces pool-uniqueness.
+- **Tests** — Tier 1 (7 unit on the resolver incl. the regression), Tier 3 (e2e: transfer to THIS machine's own nickname resolves through the real AgentServer — 404'd before). `tsc` clean.
+
+## Spec lineage
+
+§L4 of the approved `docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md` (nickname-based placement/transfer). No new authority — a convergence read-model over existing nickname state.