instar 0.28.49 → 0.28.51

package/upgrades/side-effects/0.28.52.md

@@ -0,0 +1,276 @@
+# Side-Effects Review — Compaction-recovery proxy-filter fix
+
+**Version / slug:** `0.28.52`
+**Date:** `2026-04-17`
+**Author:** `echo`
+**Second-pass reviewer:** `(this is a classifier-dedup fix with no Guard
+surface — second pass not required per skill Phase 5)`
+
+## Summary of the change
+
+Closes the topic-6795 compaction stall: `recoverCompactedSession` was
+deciding "is there pending work?" by looking at the last message in the
+topic without filtering out PresenceProxy standby messages or
+server-emitted delivery/lifecycle acks. Those are `fromUser: false` but
+they are NOT real agent responses — treating them as "agent answered" is
+what let the compaction-recovery safety net decline three consecutive
+re-inject attempts while the user sat with an unanswered question.
+
+The fix hoists the classifier that `PresenceProxy.isSystemMessage()` and
+`checkLogForAgentResponse()` already used into a shared module, adds a
+thin `findLastRealMessage(history)` walk-back helper on top, and routes
+`recoverCompactedSession` through it. Three scattered copies of the
+prefix list are now one.
+
+Files touched:
+
+- `src/messaging/shared/isSystemOrProxyMessage.ts` — new. Exports
+  `isSystemOrProxyMessage(text)` (the classifier) and `findLastRealMessage(history)`
+  (the walk-back). Thorough header comment documenting which subsystems
+  consume it and the regression anchor.
+- `src/commands/server.ts` — `recoverCompactedSession` now uses
+  `findLastRealMessage` instead of `history[history.length - 1]`. History
+  window widened 5 → 20. `checkLogForAgentResponse` now delegates to
+  `isSystemOrProxyMessage` instead of its inlined prefix list.
+- `src/monitoring/PresenceProxy.ts` — `isSystemMessage()` is now a thin
+  wrapper over `isSystemOrProxyMessage` (instance-method signature
+  preserved so existing callsites are unchanged).
+- `tests/unit/isSystemOrProxyMessage.test.ts` — new, 25 tests.
+
+## Decision-point inventory
+
+- `recoverCompactedSession` unanswered-message check — **modify** — the
+  authority that decides whether a compaction re-injection fires. The
+  decision predicate changed from "look at last message only" to "walk
+  backward skipping system/proxy, check first real message". Role
+  (authority) unchanged; correctness of the predicate improved.
+- `checkLogForAgentResponse` — **modify** — signal producer ("has the
+  agent responded since X?"). Logic unchanged, just dedup against shared
+  classifier.
+- `PresenceProxy.isSystemMessage()` — **modify** — signal producer for
+  the race guard. Logic unchanged, just dedup against shared classifier.
+- `isSystemOrProxyMessage` / `findLastRealMessage` — **new helpers** —
+  pure functions, no state, no side effects, no blocking authority of
+  their own. They are detectors; callers decide what to do with the
+  verdict.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+None new. The classifier's prefix list is identical to what
+`PresenceProxy.isSystemMessage` and the pre-fix inlined copy in
+`checkLogForAgentResponse` already used. Unit tests
+(`does NOT classify a checkmark used in narrative as a delivery ack`,
+`does NOT classify a message merely CONTAINING 🔭 later as proxy`) pin
+down the leading-prefix contract — an agent reply that *mentions* 🔭 or
+uses ✓ later in a sentence is correctly treated as a real response.
+
+The only behavior change affecting "the agent answered" detection is that
+`recoverCompactedSession` now walks PAST system/proxy entries instead of
+tripping on them. The pre-fix behavior was strictly more trigger-happy
+with declines; post-fix is strictly more trigger-happy with re-injections.
+A re-injection on an already-answered topic costs one
+`COMPACTION_RESUME_PROMPT` message plus a small session-wake — the same
+path that fires on legitimate recoveries, and well-tested. Not comparable
+to the silent 15-minute user-facing stall from the old behavior.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+1. **Pre-change under-block (the one this fixes):** recoverCompactedSession
+   accepting standby-as-answer and declining recovery. Closed.
+2. **History horizon:** `telegram.getTopicHistory(topicId, 20)` reads the
+   last 20 topic entries. If the user's unanswered question is 21+ entries
+   back AND every message in between is system/proxy, the walk returns
+   null and declines. Pre-fix used a window of 5, so this is a
+   strict improvement; but it's still finite. In practice, 20 messages of
+   pure standby/ack traffic without a single real agent reply would itself
+   be a distinct pathology (agent is completely wedged, not just
+   compacting), and the right response is escalation to stall triage —
+   not a bigger history window. Documented in the module header.
+3. **New from-agent message formats:** if a future subsystem starts
+   emitting a new kind of "not really a response" message (say, a new
+   telemetry prefix), the classifier won't know about it and recovery
+   will decline. Mitigation: the classifier is now in one place, so
+   adding the new prefix is one edit and gets all three callsites for
+   free — versus the pre-fix state where you'd need to update three
+   files and remember which ones.
+4. **Trimmed-whitespace input:** classifier trims before matching, so
+   indentation/CRLF variations are covered. Pinned by
+   `trim handling` tests.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The classifier sits at the *data-shape* layer: "given a line of text,
+is it a real agent response?" It has no knowledge of topics, sessions,
+timestamps, or recovery policy. Callers (recoverCompactedSession,
+PresenceProxy, checkLogForAgentResponse) own the *policy* — what to do
+when a message is or isn't a real response.
+
+The walk-back helper `findLastRealMessage` sits one layer up: "given a
+chronological history, find the latest real entry." Still no policy. Its
+only knowledge is that histories are chronologically ordered and that the
+classifier distinguishes real from not-real.
+
+This is the same shape as other shared classifiers in the repo
+(`detectContextExhaustion`, `isHttpIdempotent`). Appropriate fit.
+No authority is being packed into a detector, no detector is being
+smeared across three files.
+
+Alternatives considered and rejected:
+
+- **Inline the walk-back in `recoverCompactedSession` only** — would
+  re-introduce the three-copy duplication problem on the next change.
+  Rejected.
+- **Make the classifier itself decide "should recovery fire?"** — would
+  pack policy into the detector. Callers need different behaviors
+  (PresenceProxy cares about self-cancellation, recoverFn cares about
+  user turns, checkLog cares about any real agent message). Rejected.
+- **Move the walk-back into TelegramAdapter as `getLastRealMessage`** —
+  would couple a generic message-shape filter to the Telegram adapter.
+  The same logic needs to apply to Slack histories later. Rejected in
+  favor of the transport-agnostic helper.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change moves in the correct direction on the principle.
+
+Narrative breakdown:
+
+- `isSystemOrProxyMessage` is a **signal producer** — a detector on
+  textual shape. No blocking authority, no side effects, no state. It
+  emits a classification; callers choose what to do.
+- `findLastRealMessage` is also a signal producer — it transforms a
+  history into "which entry is the latest real one?" It doesn't decide
+  whether anything should fire.
+- The blocking/non-blocking authority lives in `recoverCompactedSession`
+  (which decides to inject or not) and in the CompactionSentinel
+  (which decides to retry or finalize). Neither gained new authority;
+  the existing authority now consumes a less-brittle signal.
+
+Signal strength: the classifier is prefix-based, which is fragile for
+general-purpose intent classification — but here the "signal" is a
+structural marker emitted by known server-code paths (PresenceProxy
+emits `🔭`, the server emits `✓ Delivered` via a specific code path, etc.).
+It's not inferring intent from free-text user input. Prefix matching is
+the right tool for this specific job.
+
+No brittle check is acquiring blocking authority. One authority
+(recoverCompactedSession) is migrating from a brittle predicate ("last
+message is from user?") to a robust one ("last REAL message is from
+user?"). Principle held.
+
+---
+
+## 5. Interactions
+
+- **With CompactionSentinel:** the Sentinel observes `recoverFn`'s
+  accept/reject verdict unchanged. Dedupe, retry, verify-window, and
+  finalize semantics are untouched. The fix changes WHEN recoverFn says
+  `true`, not the Sentinel's reaction to it.
+- **With PresenceProxy race guard:** PresenceProxy already used the
+  (now shared) classifier to decide whether to self-cancel on a sibling
+  standby. That logic is byte-equivalent pre and post — only the source
+  of the prefix list changed. Verified by running
+  `presence-proxy-cancel-race.test.ts` (5 tests) green.
+- **With checkLogForAgentResponse:** delegates the classifier call.
+  Function-level behavior unchanged. No new callers; same call sites
+  (stall-triage idle check, PresenceProxy "has the agent responded since
+  X"). Verified by running the broader suite green.
+- **History-window widening (5 → 20):** only affects
+  `recoverCompactedSession`. `telegram.getTopicHistory` is already
+  safe up to 50+ entries in other call sites. No performance concern —
+  reading 20 log entries is ~1-2ms.
+- **Races:** the walk is over a snapshot of the history read once per
+  call. No multi-step read, no TOCTOU window. Sentinel-level deduplication
+  already prevents concurrent recoverFn calls for the same session.
+- **Feedback loops:** recovery inject → session wakes → agent emits real
+  response → future `checkLogForAgentResponse`/walk-back sees the real
+  response, not the proxy standby that preceded it. Correctly breaks the
+  loop that previously kept the session "stuck-looking."
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** none. The classifier lives in
+  the per-agent server process.
+- **Other users of the install base:** on upgrade, agents whose
+  compaction recovery was declining due to this bug will begin
+  successfully recovering. This is the intended, silent, good behavior
+  change. Users should not notice anything except that compaction stalls
+  become shorter.
+- **External systems:** none. No new egress.
+- **Persistent state:** none. No schema changes. No agent-state migration.
+- **Log format:** `[CompactionResume]` log lines are unchanged.
+  `[Sentinel]` lifecycle lines are unchanged. A re-injection that
+  previously would have logged `recoverFn declined (no pending work or
+  session gone)` will now log the normal
+  `direct re-inject OK for topic <N>` path.
+- **Timing/runtime:** walking 20 log entries through a string-prefix
+  classifier adds <1ms to the recoverFn hot path. Sentinel timers
+  unchanged.
+
+---
+
+## 7. Rollback cost
+
+Pure code change. Revert the commit, ship a patch. No persistent state
+migration. No agent state repair. On rollback, compaction recovery
+returns to the pre-fix behavior — declining when the last message is a
+PresenceProxy standby. No user-visible regression beyond re-exposing the
+original bug.
+
+Estimated rollback effort: one revert commit + one release bump, <10 minutes.
+
+---
+
+## Conclusion
+
+Small-surface bug fix. The change:
+
+1. Closes a concrete user-visible failure (topic-6795 compaction stall,
+   repro-ed three times).
+2. Dedups three copies of a prefix list that were drifting.
+3. Adds regression coverage (25 unit tests including the exact
+   repro sequence).
+4. Moves `recoverCompactedSession` from a brittle last-message-only
+   predicate to a walk-back over filtered history.
+5. Holds to signal-vs-authority: no detector gains blocking power; one
+   authority now consumes a robust signal instead of a brittle one.
+
+Clear to ship.
+
+---
+
+## Evidence pointers
+
+- Reproduction: `.instar/shared-state.jsonl` entries around topic 6795 at
+  16:08:14 / 16:13:xx / 16:18:xx logged the three
+  `recoverFn declined (no pending work or session gone)` lines; topic
+  history in `.instar/telegram-messages.jsonl` at each decline point
+  shows the preceding message was a `🔭 Echo is currently updating the
+  ledger spec…` PresenceProxy standby.
+- Pre-fix behavior: `git show <pre-fix>:src/commands/server.ts` around
+  the `recoverCompactedSession` definition shows
+  `const lastMsg = history[history.length - 1]; if (lastMsg?.fromUser) { ... }`.
+- Post-fix behavior: `findLastRealMessage(history)` returns the last
+  non-system/non-proxy entry; the decision predicate sees the real user
+  turn.
+- Tests: `tests/unit/isSystemOrProxyMessage.test.ts` — 25 passing tests.
+  Explicit `topic-6795 repro` case asserts the helper finds the user
+  question past trailing proxy + ack entries.

package/upgrades/side-effects/pre-push-gate-ci-scope.md

@@ -0,0 +1,104 @@
+# Side-Effects Review — pre-push gate: CI scope fix
+
+**Version / slug:** `pre-push-gate-ci-scope`
+**Date:** `2026-04-17`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Modifies `scripts/pre-push-gate.js` in two ways: (1) wraps section 5 (side-effects artifact check) in `if (!process.env.CI)`, so the check runs only when developers push locally and is skipped in GitHub Actions; (2) adds `2>/dev/null` to the `HEAD~1` stderr fallback in section 3's git diff command, stopping stderr from leaking through the try/catch into the test output in shallow-clone CI environments. No `src/` files are touched — only the gate script itself.
+
+## Decision-point inventory
+
+- `scripts/pre-push-gate.js` section 5 — **modify** — narrows the scope of the side-effects artifact check from "always" to "not in CI". The check itself is unchanged; only its execution context is restricted.
+- `scripts/pre-push-gate.js` section 3 — **modify** — cosmetic: suppresses stderr noise from a git fallback command. No decision logic involved.
+
+---
+
+## 1. Over-block
+
+No block/allow surface for messages or agent actions — not applicable in the traditional sense.
+
+Within the gate's own domain: the change *reduces* over-block. Previously the gate would reject any CI run on a contributor branch that was cut before the side-effects artifact for the current version was added to main. That's a false positive — the contributor didn't violate the process, the artifact simply hadn't been added to main yet when they branched. The fix stops those legitimate branches from being blocked.
+
+No new rejection surface is introduced.
+
+---
+
+## 2. Under-block
+
+The gate now allows CI runs that are missing the side-effects artifact. This is an intentional scope reduction: CI is not the enforcement point. The enforcement points are:
+
+1. The pre-commit hook (`scripts/instar-dev-precommit.js`) — runs per-commit on the developer's machine.
+2. The pre-push hook (this gate, section 5) — runs on the developer's machine at push time.
+
+Both hooks run before code reaches CI. If a developer bypasses them (e.g., `--no-verify`), section 5 in CI would have caught it — and now it won't. This is a real reduction in defense depth for the `--no-verify` bypass case.
+
+Mitigation: `--no-verify` bypasses are visible in git history (the commit won't have the artifact). The pre-push gate also re-checks at the release-cut step when NEXT.md is renamed to a versioned file — which does happen locally, not in CI. The net under-block exposure is: a developer who uses `--no-verify` and then somehow gets their branch merged without a local push. This is a narrow path that the review process (PR review, merge gating) is expected to catch.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The gate is a structural process-enforcement check, not a message-content gate. Section 5 is explicitly scoped to "push time" in its own comment. CI is not push time — it's post-push. Running a push-time check in CI creates a category mismatch that produces false failures on valid contributor branches.
+
+The fix is at the correct layer: the `if (!process.env.CI)` guard is a simple execution-context discriminator applied directly to the check that's miscategorized for CI. No rearchitecting needed.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface.
+
+The gate operates on developer process compliance (file existence, git metadata), not on message content or agent behavior. The signal-vs-authority principle applies to decision points that evaluate messages or constrain agent information flow. A CI scope guard on a developer process check is outside that domain.
+
+The change itself is a pure scope restriction — it *removes* an execution context from an existing check. No new brittle logic is added. No new authority is claimed.
+
+---
+
+## 5. Interactions
+
+**Shadowing:** The pre-commit hook and the local pre-push hook both enforce section 5's requirement. This change scopes section 5 to local-only. The pre-commit hook is unchanged — it still runs on every commit. No shadowing occurs.
+
+**Double-fire:** Section 5 currently runs both locally (pre-push) and in CI (via the test that invokes the gate script). After this change it only runs locally. No double-fire; in fact we're eliminating the accidental double-enforcement.
+
+**Races:** No shared state involved. The check reads filesystem files (upgrade guides, side-effects dir). No concurrent access concern.
+
+**Feedback loops:** None. The gate is a one-way exit check with no input to any system that feeds back.
+
+---
+
+## 6. External surfaces
+
+- **Other agents:** No effect. The gate runs only in the instar repo's CI and in developer environments.
+- **Install base users:** No effect. This is a developer tooling change, not a runtime change. `instar` as installed by users has no pre-push gate.
+- **External systems:** No effect.
+- **Persistent state:** No effect.
+- **Timing/runtime:** The `CI` env var is set by GitHub Actions automatically for all runs. No timing dependency — it's present or absent at process start.
+
+---
+
+## 7. Rollback cost
+
+Pure code change in `scripts/pre-push-gate.js`. Revert and ship a patch. No persistent state, no migration, no agent state repair. The only user-visible effect during the rollback window would be contributor PR CI runs again failing on missing side-effects artifacts — which is the exact condition we're fixing, not a new regression.
+
+---
+
+## Conclusion
+
+The change is narrow and correct. It scopes section 5 of the pre-push gate to local developer contexts only, which matches the intent stated in the gate's own comment ("at push time"). The under-block exposure (a developer using `--no-verify` evading CI detection) is real but narrow: it requires bypassing two local enforcement hooks AND getting a PR merged without review catching the missing artifact. The pre-commit hook and PR review process are the remaining guards. The fix is clear to ship.
+
+No design changes were made as a result of the review.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/pre-push-gate.test.ts` — all 6 tests pass locally after the change.
+- `CI=true node scripts/pre-push-gate.js` — exits 0 on the current branch (which has the 0.28.49 versioned guide with fix/feature language but no fresh side-effects artifact for that version in CI context).
+- Without `CI`, the gate still enforces section 5 (verified by the existing passing local test that runs the gate in a non-CI shell).

package/upgrades/side-effects/skill-port-dynamic-resolution.md

@@ -0,0 +1,104 @@
+# Side-Effects Review — default skills: dynamic localhost port
+
+**Version / slug:** `skill-port-dynamic-resolution`
+**Date:** `2026-04-17`
+**Author:** `dawn`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Two source changes. In `src/commands/init.ts`, every `http://localhost:${port}/...` URL inside `installBuiltinSkills` (and adjacent helpers that share the same file) is rewritten to emit `http://localhost:\${INSTAR_PORT:-${port}}/...`, so the generated `.claude/skills/*/SKILL.md` files contain a shell-expandable port reference instead of a number baked in at install time. In `src/core/PostUpdateMigrator.ts`, a new `migrateSkillPortHardcoding()` scans existing default-skill files for bare `http://localhost:NNNN/` URLs and rewrites them to `http://localhost:${INSTAR_PORT:-NNNN}/`, preserving the original port as the fallback default. The migration is scoped to the 14 known-default skill names and is idempotent. Test coverage: `tests/unit/PostUpdateMigrator-skillPortHardcoding.test.ts` — 6 cases.
+
+## Decision-point inventory
+
+- `src/commands/init.ts` `installBuiltinSkills` — **modify** — replaces hardcoded port templating with runtime-expandable pattern. 93 occurrences, mechanical find/replace, all inside backtick template strings for shell-executed content.
+- `src/core/PostUpdateMigrator.ts` `migrateSkillPortHardcoding` — **add** — new migration method. Called from `migrate()` between `migrateBuiltinSkills` and `migrateSelfKnowledgeTree`. Scoped to a fixed allowlist of 14 default skill names.
+- `tests/unit/PostUpdateMigrator-skillPortHardcoding.test.ts` — **add** — regression coverage for the migration.
+
+---
+
+## 1. Over-block
+
+No block/allow surface. The change is runtime port resolution in user-project skill files. No message content or agent action is gated.
+
+Within the migration's own domain: the scan matches `/http:\/\/localhost:(\d+)\//g` in the default-skill set. This pattern is narrow enough that it will not false-positive on natural-language references ("localhost:4040" mentioned in prose without the URL form is untouched). Files outside the 14-name allowlist are never read, so custom skills are never modified — a principle the test suite asserts explicitly.
+
+---
+
+## 2. Under-block
+
+No block surface existed before this change. The migration adds no new enforcement — it is a one-way content rewrite. There is nothing to under-block.
+
+Edge case: if a user had a default-skill file with a mix of the new dynamic pattern and stray hardcoded ports (e.g., partial manual edits), the idempotency guard (`includes('${INSTAR_PORT:-')`) will cause the migration to skip the file entirely rather than finish the rewrite. That is the safe direction — migrating a partially-edited file risks corrupting the user's edits. Users in that state can manually finish the rewrite or delete the file and let `installBuiltinSkills` regenerate it.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The change is at the correct layer. The root cause was install-time templating of a value that should have been runtime-resolved. Fixing the template is the direct fix; fixing existing user files via migration is the correct catch-up mechanism. Neither change rearchitects the skill system — skills remain static markdown files, the only change is that a value inside them resolves later.
+
+The dynamic pattern `${INSTAR_PORT:-PORT}` uses POSIX shell parameter expansion, the same primitive the rest of the Instar shell surface depends on. It is a recognized idiom inside curl-heavy bash content, not a novel construct the user has to learn.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface.
+
+The change is a content rewrite inside skill files. It does not evaluate messages, gate agent actions, or constrain information flow. Signal-vs-authority applies to decision points that judge messages or block work. A port-expansion template does neither.
+
+---
+
+## 5. Interactions
+
+**Shadowing:** `installBuiltinSkills` and `migrateSkillPortHardcoding` target overlapping surface. Order matters: `migrateBuiltinSkills` runs first (non-destructive, writes only missing files), then `migrateSkillPortHardcoding` runs (rewrites existing files). A skill newly written by `installBuiltinSkills` in the same migration pass already uses the dynamic pattern, so `migrateSkillPortHardcoding` will see the `${INSTAR_PORT:-` marker and no-op. No double-processing.
+
+**Double-fire:** `migrateSkillPortHardcoding` is idempotent — once a file contains the dynamic marker, it is skipped. Test case `is idempotent on a second run after migration` covers this explicitly.
+
+**Races:** `PostUpdateMigrator.migrate()` is sequential and runs once per `instar` update. No concurrent access to the same skill file is expected. If two updaters ran simultaneously, they would both read the hardcoded content, both rewrite it, and the second write would overwrite the first with identical content — no corruption.
+
+**Feedback loops:** None. The migration is a one-shot rewrite; the rewritten content does not feed back into any system.
+
+---
+
+## 6. External surfaces
+
+- **Other agents:** Each agent running instar will get the migration on next `instar` upgrade. Agents on non-default ports gain working skills; agents on port 4040 see no behavioral change (the fallback matches their previous hardcoded value).
+- **Install base users:** Users with customized skill files (renamed default skills, heavily edited content) are protected by the allowlist and the dynamic-marker idempotency check. The migration touches only the 14 canonical default-skill files, and only if they still contain the bare-port pattern.
+- **External systems:** None. The URL targets are all `localhost` — no external traffic shape changes.
+- **Persistent state:** Skill files on disk are rewritten in place. No database, no config, no registry is touched. Rollback = `git checkout` of the skill file or `rm` and re-run `installBuiltinSkills`.
+- **Timing/runtime:** The `${INSTAR_PORT:-NNNN}` expansion runs at shell invocation time. An agent with `INSTAR_PORT` unset gets the fallback; with it set, gets the override. Zero-cost at skill-read time; one environment variable lookup per curl.
+
+---
+
+## 7. Rollback cost
+
+Low. Revert: `git revert` the two source commits; the emitted skills would return to hardcoded ports, matching pre-fix behavior. Users who already ran the migration would keep their dynamic-pattern skills, which continue to work (the fallback equals the previous hardcoded value). No persistent state to undo, no agent state to repair, no user communication required.
+
+Narrow risk: if a user's `INSTAR_PORT` env var is set to an invalid value (e.g., a port the server isn't listening on), curls will fail after this change where they would have succeeded before on the hardcoded default. Mitigation: the variable is only consulted if the user explicitly exported it. The intersection of "exported `INSTAR_PORT`" and "set it wrong" is small and self-inflicted; the fix for that case is `unset INSTAR_PORT` or set it correctly.
+
+---
+
+## Conclusion
+
+The change is narrow, well-scoped, and covered by regression tests. The template fix is mechanical and safe. The migration is scoped to a known allowlist, idempotent, and respects user customizations. The under-block surface is zero; the over-block surface is zero. The worst case in rollback is a return to the original bug, which affected only users on non-default ports and is already worked around today by hand-sed. Ship.
+
+No design changes were made as a result of the review.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/PostUpdateMigrator-skillPortHardcoding.test.ts` — 6 tests pass:
+  - rewrites hardcoded ports in a default skill
+  - leaves already-dynamic skills untouched (idempotent)
+  - does not touch custom (non-default) skills
+  - is idempotent on a second run after migration
+  - skips when the skill file does not exist
+  - preserves the original port number in the fallback
+- Live template verification: `node -e "const {installBuiltinSkills}=require('./dist/commands/init.js'); ..."` against a temp dir shows 13 of 14 default skills emit `localhost:${INSTAR_PORT:-4040}` and zero emit bare `localhost:4040` (the 14th skill, `autonomous`, is a stub that deploys separately and has no localhost URLs).
+- Source-side verification: `grep -c 'localhost:${port}' src/commands/init.ts` = 0 after the rewrite (was 93).