instar 1.3.45 → 1.3.46

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-28T02:17:30.185Z",
-  "instarVersion": "1.3.45",
+  "generatedAt": "2026-05-28T02:19:53.690Z",
+  "instarVersion": "1.3.46",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1489,7 +1489,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "de0ac7e9acd815a17f3adf06b1154fcb0fd4a265f0e51e38509f811902e43c1e",
+      "contentHash": "002d9267e321809eb996c0e30bd35d7eeb67eb3e11b09dd8cfbf66e9bd215b49",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {
@@ -1521,7 +1521,7 @@
       "type": "subsystem",
       "domain": "communication",
       "sourcePath": "src/lifeline/TelegramLifeline.ts",
-      "contentHash": "6f5b9a817019b735b9afe3fded858ce713c8bc770b1d3bf018b65905eef25378",
+      "contentHash": "4a2f251ab4d091cf62d9826a1738729838775254ff00d6c743787193ca48dd8b",
       "since": "2025-01-01"
     },
     "subsystem:orphan-process-reaper": {

package/src/scaffold/templates.ts

@@ -443,6 +443,12 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 
 **Use private views for sensitive content. Use Telegraph for public content.**
 
+**Agent Updates topic (self-broadcasts about ships, restarts, updates)** — When narrating a ship, an update I just applied, or a restart I just completed (e.g. "Just shipped X", "Back up and running on vN", "Bounced cleanly after the update"), route the message through the post-update channel so it lands in the dedicated Agent Updates topic — NOT the active session topic the user happened to be chatting in.
+- Post: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/post-update -H 'Content-Type: application/json' -d '{"text":"Your update narration here"}'\`
+- The endpoint resolves the Updates topic from state server-side; you cannot specify a topic and you should not try to.
+- If Updates is not configured, the endpoint returns 400 — do NOT fall back to sending in the active topic. Update-class messages belong in Updates or they don't go out at all.
+- **When to use** (PROACTIVE — this is the trigger): the moment I am about to author a conversational message whose subject is *me* shipping, updating, or restarting — including post-restart "I'm back" confirmations — I use this endpoint. Authoring such a message via the standard Telegram reply path puts release chatter into whatever conversation the user was last in, which is the bug this routing closes.
+
 **Secret Drop** — Securely collect secrets (API keys, passwords, tokens) from users without exposing them in chat history.
 - Request a secret: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/secrets/request -H 'Content-Type: application/json' -d '{"label":"OpenAI API Key","description":"Needed for GPT integration","topicId":TOPIC_ID}'\`
 - The response includes a one-time URL (\`localUrl\` and \`tunnelUrl\`). Send this link to the user.

package/upgrades/1.3.46.md

@@ -0,0 +1,46 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Update-class messages now consistently land in the dedicated **Agent Updates** topic instead of leaking into random conversations. Three separate emitters were each picking a topic differently and two picked the wrong one:
+
+1. The lifeline's HTTP-426 version-skew alert ("Heads up: my server auto-updated to vN but my lifeline is still on vM…") was being sent to whichever topic the user happened to be typing in when the forward came back. Now it resolves `agent-updates-topic` from server state and routes there, falling back to the Lifeline topic if Updates is unset — never the inbound topic.
+2. The `ForegroundRestartWatcher` "Applying update to vN — restarting now" heads-up was routing through the central `notify()` helper without an explicit topic, which silently defaulted to the **Attention** topic. The caller now reads `agent-updates-topic` and passes it explicitly, falling through to the prior Attention default only when Updates is unconfigured.
+3. Agent-authored ship/restart narration ("Quick heads-up: shipped X", "Back up and running on vN") had no template guidance steering it through the post-update channel — it landed in whatever topic the session was bound to. A new CLAUDE.md section + idempotent migration teaches every existing agent to route those self-broadcasts through `POST /telegram/post-update`.
+
+## What to Tell Your User
+
+- My update notifications, restart heads-ups, and post-restart "I'm back" messages will now show up in the Agent Updates topic where they belong, instead of leaking into whatever conversation you happened to be in when an update fired. If you don't see them in random topics any more — that's the fix working.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Lifeline version-skew alert resolves Updates topic | Automatic — no agent action required. The lifeline reads `agent-updates-topic` state on every 426 episode and routes the alert there; falls back to the Lifeline topic if Updates is unset. |
+| `ForegroundRestartWatcher` "applying update" routes to Updates | Automatic — no agent action required. The pre-restart heads-up now consults `agent-updates-topic` and falls through to the prior Attention default only when unset. |
+| Agent self-broadcast guidance (CLAUDE.md template + migration) | Existing agents pick up the new section via `PostUpdateMigrator.migrateClaudeMd()` on next update. New agents get it via `init`. Trigger: any conversational message whose subject is "I shipped / I updated / I restarted" → `curl -X POST .../telegram/post-update` instead of authoring in the active topic. |
+
+## Evidence
+
+- Bug report: Justin, 2026-05-27 (topic 14668), with screenshot of two update-narration messages landing in a Case Study topic instead of the Agent Updates topic.
+- Diagnosis: three independent emitter paths each picking a topic differently — two wired wrong.
+- Spec: `docs/specs/UPDATE-MESSAGE-TOPIC-ROUTING-SPEC.md` (Fix 1 lifeline / Fix 2 watcher / Fix 3 template + migration).
+- ELI16 summary: `docs/specs/UPDATE-MESSAGE-TOPIC-ROUTING-ELI16.md`.
+- Tests added (3 files, 20 new tests, all green):
+  - `tests/unit/lifeline/version-skew-alert-routing.test.ts` — source-level assertions that `handleVersionSkew` resolves Updates via the new `resolveUpdatesAlertTopic()` helper, never the inbound topic; preserves 24h dedupe; drops cleanly when both Updates and Lifeline topics are unset.
+  - `tests/unit/foreground-restart-watcher-notify-routing.test.ts` — source-level assertions that the `onRestartDetected` callback reads `agent-updates-topic` and passes it explicitly to `notify()`; uses `|| undefined` so the unset case falls through to the prior central-notify default.
+  - `tests/unit/PostUpdateMigrator-updateTopicSelfBroadcast.test.ts` — full migration test: idempotency on second run, preserves existing CLAUDE.md content, graceful skip when CLAUDE.md is missing, parity with the source template.
+- Smoke suite: 2941/2941 passed.
+- Migration parity: the two code fixes ride the normal dist refresh on update; the CLAUDE.md template change has a dedicated migration in `PostUpdateMigrator` so existing agents pick it up, not just newly-initialized ones.
+
+## Risk + Rollback
+
+- Risk: **low**. Each fix is a pure routing change with a documented fallback. No contract change, no schema migration, no rolling restart needed beyond the standard post-update flow.
+- Rollback: revert the PR. The lifeline 426 path returns to sending the alert to the inbound topic; the foreground watcher path returns to the central-notify Attention default; the CLAUDE.md section remains in already-migrated agents but does no harm (it's awareness, not enforcement).
+
+## Follow-Ups (tracked, not in this PR)
+
+- Structural enforcement of Fix 3 via a PreToolUse hook that detects agent-authored ship/update narration and redirects to `/telegram/post-update` — the Structure-over-Willpower version of the template guidance.
+- Audit of remaining `notify('IMMEDIATE', 'system', …)` callsites in `commands/server.ts` for any other update-class messages that should route to Updates rather than Attention.