instar 1.1.4 → 1.2.2

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-21T04:11:40.504Z",
-  "instarVersion": "1.1.4",
+  "generatedAt": "2026-05-21T04:38:07.750Z",
+  "instarVersion": "1.2.2",
   "entryCount": 190,
   "entries": {
     "hook:session-start": {
@@ -392,7 +392,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -400,7 +400,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -408,7 +408,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -416,7 +416,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -424,7 +424,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -432,7 +432,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -440,7 +440,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -448,7 +448,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -456,7 +456,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -464,7 +464,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -472,7 +472,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -480,7 +480,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -488,7 +488,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -496,7 +496,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -504,7 +504,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -512,7 +512,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -520,7 +520,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -528,7 +528,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -536,7 +536,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -544,7 +544,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -552,7 +552,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -560,7 +560,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -568,7 +568,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -576,7 +576,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -584,7 +584,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -592,7 +592,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -600,7 +600,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -608,7 +608,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -616,7 +616,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -624,7 +624,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -632,7 +632,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -640,7 +640,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -648,7 +648,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -656,7 +656,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -664,7 +664,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -672,7 +672,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -680,7 +680,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -688,7 +688,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -696,7 +696,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -704,7 +704,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -712,7 +712,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -720,7 +720,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -728,7 +728,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -744,7 +744,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "2eccf8b9643cd244125cd69b2453db09ae642a2514e1237541e24086a17347bc",
+      "contentHash": "e0abd503b434c2df51917a9a68f8a9a2d514c61faf43012712878282eb9ccf8d",
       "since": "2025-01-01"
     },
     "cli:init": {

package/upgrades/1.1.4.md

@@ -1,42 +1,143 @@
-# Upgrade Guide — vNEXT
+# Upgrade Guide — v1.2.0 (telegram-history-backfill + test-env GIT_DIR hardening)
 
-<!-- bump: patch -->
-<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- bump: minor -->
 
 ## What Changed
 
-**fix(test-env): close the inherited-GIT_DIR failure class.**
+Two changes ship together. The headline is the new operator-driven
+recovery primitive; the test-env hardening from PR #286 rides along in
+the same release.
+
+**1. New: telegram-history-backfill (MTProto recovery primitive).** A
+script-tier path to restore `topic-memory.db` after a local-store loss
+event. The 2026-05-20 cascade (a Node 22→25 host swap broke
+`better-sqlite3`; the recovery procedure restored the module but left
+topic-memory's local mirror near-empty) exposed a durable gap: the
+Telegram Bot API cannot fetch chat history, so any local mirror loss
+was previously permanent. Authenticates as the operator's account via
+gramjs (MTProto), iterates forum topics, writes idempotently via the
+existing `UNIQUE(message_id, topic_id)` constraint + `INSERT OR IGNORE`.
+Three new files under `scripts/`:
+
+- `scripts/lib/topic-memory-importer.mjs` — pure-DB importer with batch
+  transactions and INSERT OR IGNORE idempotency.
+- `scripts/lib/telegram-historian.mjs` — gramjs wrapper. Auth, topic
+  listing, per-topic iteration. **Read-only Telegram posture** — no
+  send/edit/delete method is exposed.
+- `scripts/telegram-history-backfill.mjs` — CLI entry. Three driving
+  modes for auth (interactive stdin, `--phone` + `--code-file` polling
+  for SMS, `--password-file` for 2FA). The file-poll mode supports
+  autonomous operation paired with instar's Secret Drop web form
+  (avoids Telegram's anti-phishing "code was shared in a chat" block).
+
+Session string stored at `~/.local/share/instar-echo-secrets/` mode
+0600, outside any git tree.
+
+**2. fix(test-env): close the inherited-GIT_DIR failure class.** Carried
+forward from PR #286. When git invokes a hook (`.husky/pre-push` runs
+`npm run test:smoke`), it sets `GIT_DIR` / `GIT_WORK_TREE` /
+`GIT_INDEX_FILE` / `GIT_OBJECT_DIRECTORY` / `GIT_COMMON_DIR` on the
+child env. Those variables override cwd-based repo resolution for
+every descendant git process, so test fixtures that did
+`git init && git commit` in a tmpdir actually committed into the
+parent repo on whichever branch was checked out. That's what landed
+`# Test Project` over the project's `README.md` on `main` via PRs #130
+and #277 — the README clobber shipped to npm in the v1.1.x series
+before PR #285 restored it.
+
+The fix closes the failure class in five interlocking layers:
+
+1. **`tests/vitest-setup.ts` strips the GIT_DIR family** from
+   `process.env` before any test file loads. Single-line root-cause fix.
+2. **`tests/helpers/git-test-env.ts` exports `sanitizedGitEnv()`** for
+   fixtures that pass their own `env` object to `spawnSync` /
+   `execFileSync`. Defense-in-depth on top of Layer 1.
+3. **`scripts/pre-push-fixture-guard.mjs`** runs in `.husky/pre-push`
+   before the smoke tests and refuses pushes whose ahead-of-upstream
+   commits carry the historical fixture signature (author email in
+   `{test@instar.local, t@t.com, t@e.com, test@test.com}` or subject
+   matching `Initial commit` / `seed` / `init` / `Worktree commit N`).
+4. **`scripts/check-repo-invariants.mjs`** runs as a dedicated
+   `Repo Invariants` CI job and fails the build if `README.md` drops
+   below 100 lines or if `file-0.txt` / `seed` appear at repo root.
+5. **Removed `file-0.txt` and `seed`** stowaway files from repo root —
+   fixture droppings that would have falsely passed Layer 4 on the
+   PR adding it.
 
-When git invokes a hook (`.husky/pre-push` runs `npm run test:smoke`), it sets `GIT_DIR` / `GIT_WORK_TREE` / `GIT_INDEX_FILE` / `GIT_OBJECT_DIRECTORY` / `GIT_COMMON_DIR` on the child env. Those variables override cwd-based repo resolution for every descendant git process, so test fixtures that did `git init && git commit` in a tmpdir actually committed into the parent repo on whichever branch was checked out. That's what landed `# Test Project` over the project's `README.md` on `main` via PRs #130 and #277 — the README clobber shipped to npm in the v1.1.x series before PR #285 restored it.
-
-This release closes the failure class in five interlocking layers:
-
-1. **`tests/vitest-setup.ts` strips the GIT_DIR family** from `process.env` before any test file loads. Single-line root-cause fix — no test in the suite can inherit the dangerous overrides from the parent pre-push environment.
-
-2. **`tests/helpers/git-test-env.ts` exports `sanitizedGitEnv()`** for fixtures that pass their own `env` object to `spawnSync` / `execFileSync`. Applied to the three fixtures whose write patterns are visible in PR #130's diff (`worktree-monitor.test.ts`, `SafeGitExecutor.test.ts`, `rich-profile-integration.test.ts`). Defense-in-depth on top of Layer 1.
-
-3. **`scripts/pre-push-fixture-guard.mjs`** runs in `.husky/pre-push` before the smoke tests and refuses pushes whose ahead-of-upstream commits carry the historical fixture signature — author email in `{test@instar.local, t@t.com, t@e.com, test@test.com}` or subject matching `Initial commit` / `seed` / `init` / `Worktree commit N`. Bypass for legitimate test-only branches: `INSTAR_PRE_PUSH_FIXTURE_GUARD_SKIP=1`.
-
-4. **`scripts/check-repo-invariants.mjs`** runs as a dedicated `Repo Invariants` CI job and fails the build if `README.md` drops below 100 lines or if `file-0.txt` / `seed` appear at repo root. Final structural safety net; threshold overridable via `INSTAR_README_MIN_LINES`.
-
-5. **Removed `file-0.txt` and `seed`** stowaway files from repo root — fixture droppings from prior incidents that would have falsely passed Layer 4 on the PR adding it.
+## Evidence
 
-Spec: `docs/specs/test-env-isolation.md`. ELI16: `docs/specs/test-env-isolation.eli16.md`. Side-effects review: `upgrades/side-effects/test-env-isolation.md`.
+**Backfill — reproduction prior:** in topic 10873 on 2026-05-20, after
+Echo's better-sqlite3 native-module cascade recovery, the agent's local
+`topic-memory.db` showed 98 messages across 7 topics where the
+operator's Telegram client showed thousands across 100+ topics. The
+agent had no path to fetch the missing rows — Bot API has no
+history-fetch primitive.
+
+**Backfill — reproduction after:** ran against the lifeline supergroup
+(`-1003742343280`) on 2026-05-20T21:00:27Z. Result:
+`topics=101 fetched=10308 inserted=10207 skipped=101`. The 101
+skipped rows match the pre-existing on-disk count exactly — the
+UNIQUE constraint + `INSERT OR IGNORE` correctly de-duplicated the
+overlap, no doubles introduced. Topic 10873 went from 43 to 93
+messages, restoring the full deployment-lockdown arc.
+
+**Backfill — idempotency:** verified by
+`tests/unit/topic-memory-importer.test.ts` (12 cases). Re-running the
+same batch produces zero new inserts; partial-overlap re-run inserts
+only the new messages; same message_id across different topics is not
+a duplicate; FTS index stays clean across re-runs; a regression case
+reproduces the exact "post-truncation overlap" shape from the
+2026-05-20 incident.
+
+**Test-env GIT_DIR — reproduction prior:** the README clobber on
+`main` was reproduced before the fix landed: `gh api
+repos/JKHeadley/instar/contents/README.md --jq .size` returned `7`
+(the literal text `# Test\n`) prior to PR #285. PR #285 restored the
+README; PR #286 closed the underlying class so the same regression
+cannot recur. Test-fixture pollution detection was verified end-to-end:
+against a tmpdir repo with a commit subject `Initial commit`,
+`node scripts/pre-push-fixture-guard.mjs` exits 1 and names the
+offending commit. Repo-invariant detection was verified end-to-end:
+against a repo where `README.md` has been trimmed to a single line,
+`node scripts/check-repo-invariants.mjs` exits 1 and reports the line
+count.
 
 ## What to Tell Your User
 
-Nothing user-visible. This release hardens instar's own development pipeline against a class of bug that, while invisible to running agents, had been quietly corrupting our published README. Agents continue to behave identically.
-
-If a contributor asks why their push is suddenly refused with a fixture-pollution guard error, the script's own output includes recovery instructions — usually resetting past a stray commit and pushing again.
+- "I can now restore Telegram message history into my local store if it ever gets wiped again. Tell me 'back up our Telegram history' and I run a one-time auth flow with you (phone number, then a one-time code through a secure form, not through this chat) and walk the supergroup top to bottom. The whole thing is read-only on the Telegram side and the code never passes through our chat, so Telegram does not flag the login."
+- "The recovery itself is safe to re-run. If I get interrupted partway through, I just run it again — there is built-in deduplication that means existing messages are skipped, not duplicated."
+- "Nothing user-visible from the test-env GIT_DIR fix carried in from PR 286. This release hardens instar's own development pipeline against a class of bug that, while invisible to running agents, had been quietly corrupting our published README. Agents continue to behave identically."
 
 ## Summary of New Capabilities
 
-This release is a pure hardening fix. No new runtime capabilities for agents. The new pre-push and CI guards are infrastructure for the instar-developing agent and direct contributors only.
-
-## Evidence
-
-The README clobber on `main` was reproduced before the fix landed: `gh api repos/JKHeadley/instar/contents/README.md --jq .size` returned `7` (the literal text `# Test\n`) prior to PR #285. PR #285 restored the README; this PR closes the underlying class so the same regression cannot recur.
-
-Test-fixture pollution detection was verified end-to-end: against a tmpdir repo with a commit subject `Initial commit`, `node scripts/pre-push-fixture-guard.mjs` exits 1 and names the offending commit. Against the same repo with the env bypass set, the script exits 0. Repo-invariant detection was verified end-to-end: against a repo where `README.md` has been trimmed to a single line, `node scripts/check-repo-invariants.mjs` exits 1 and reports the line count; against a healthy repo, it exits 0.
-
-14 new tests across the env-strip regression, the fixture-guard, and the invariants script. The three refactored fixtures (`worktree-monitor.test.ts`, `SafeGitExecutor.test.ts`, `rich-profile-integration.test.ts`) retain their pre-existing 45+ test assertions.
+| Capability | How to Use |
+|-----------|-----------|
+| Telegram history backfill (script tier) | Operator-triggered. One-time auth via `node scripts/telegram-history-backfill.mjs --auth --phone +X...` plus a Secret Drop form for the SMS code, then `--chat <supergroup-id>` to walk every topic. |
+| Idempotent topic-memory imports | Built on the existing `UNIQUE(message_id, topic_id)` constraint plus `INSERT OR IGNORE`. Re-running the backfill is a no-op for already-imported rows. |
+| Session-string persistence | Stored at `~/.local/share/instar-echo-secrets/telegram-mtproto.session` (mode 0600, outside any git tree). Re-runs after the first auth are non-interactive. |
+| GIT_DIR-leak hardening (carried from #286) | Automatic. Test runner strips the GIT_DIR env family before any test loads; pre-push fixture guard refuses pushes carrying fixture-style commits; CI repo-invariants job catches README clobbers and stowaway files. |
+
+## Deferred (Tracked Follow-ups)
+
+- Promotion of the backfill to a full `src/messaging/TelegramHistorian.ts`
+  feature with three-tier tests (integration + e2e), an HTTP route on
+  the agent server, a CLI subcommand on the `instar` binary, an
+  agent-template update so every agent surfaces it, and a migration
+  parity entry for existing agents. The script-tier primitive shipping
+  now is the proof of concept and the recovery delivery; the durable
+  feature is the next PR.
+- Bitwarden as the canonical credential source. The credentials live
+  in BW already (secure-note item created during the auth handshake),
+  but the script reads from the sealed local file at
+  `~/.local/share/instar-echo-secrets/telegram-mtproto.json`. A small
+  follow-up wires the script to pull from `bw get` when BW is
+  unlocked, falling back to the sealed file when not.
+- Secret Drop hardening — the bridge that pulls a submitted code out
+  of the in-memory store and writes it to the auth script's poll file
+  had a parsing bug on first ship that consumed the code without
+  extracting it, losing the value. Server-side fix planned: stop
+  auto-deleting submissions on first retrieve; rely on the existing
+  5-minute timeout for cleanup; add an explicit `?consume=true`
+  parameter for callers that want one-shot semantics. Design approved
+  by operator 2026-05-20; implementation is the next PR after this
+  one lands.

package/upgrades/1.2.1.md

@@ -0,0 +1,71 @@
+# Upgrade Guide — v1.2.1 (Secret Drop hardening — non-destructive retrieve + stuck-consumer event)
+
+<!-- bump: patch -->
+
+## What Changed
+
+The `/secrets/retrieve/<token>` endpoint is now **non-destructive by
+default**. Repeated calls return the same value until the in-memory
+5-minute cleanup timer fires. Callers that need one-shot semantics opt
+in by appending `?consume=true` to the URL.
+
+Three concrete surface changes in `src/server/SecretDrop.ts` and
+`src/server/routes.ts`:
+
+1. **Two new methods on `SecretDrop`.** `peekReceived(token)` returns
+   the submission without removing it; `consumeReceived(token)` returns
+   AND removes it. The existing `getReceived(token)` is preserved as a
+   back-compat alias for `consumeReceived(token)` so no caller breaks.
+
+2. **The retrieve route honors `?consume=true`.** Default behavior is
+   `peek`. The response includes a `consumed: boolean` field so callers
+   can self-check which path ran.
+
+3. **Stuck-consumer event.** If a submission lingers in the in-memory
+   store for >60 seconds without being explicitly consumed, every
+   registered listener is invoked with a `StuckConsumerEvent`. The
+   default route-layer listener routes a `[secret-drop-stuck]` system
+   message to the bound topic's agent session, giving the operator a
+   visible cue that the consumer chain broke.
+
+## Evidence
+
+Reproduction prior: on 2026-05-20 in topic 10873, a bridge script
+called `/secrets/retrieve/<token>`, the server returned the submitted
+SMS code AND deleted it atomically, and the bridge's parser dropped
+the value on the way to disk. The code was lost; Telegram had to send
+a fresh one. Pattern verified end-to-end in
+`tests/unit/secret-drop-hardening.test.ts` ("regression: 2026-05-20
+lost-SMS-code scenario"): the test reproduces the buggy-consumer drop
+and asserts that under the hardening a retry succeeds because the
+submission is still in the store.
+
+Reproduction after: same buggy-consumer flow. First call returns the
+value AND it stays in the store. The buggy parser fails. Second call
+returns the value again. Caller fixes the parse and explicitly
+consumes. No code is lost.
+
+Idempotency, grace-period, and listener-isolation contracts verified
+by 13 unit cases. The pre-existing `tests/unit/SecretDrop.test.ts`
+suite (25 cases) continues to pass — no back-compat regressions.
+
+## What to Tell Your User
+
+- "I made my own secret-handling more forgiving. The bug that lost your one-time code earlier today can't repeat without a deliberate opt-in — my pickup process can now retry a failed handoff inside the 5-minute window instead of losing the value on the first attempt. And if something does sit unread for more than a minute, I now get a visible alert telling me to look at it, rather than silently waiting on a value that's already gone."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Non-destructive retrieve (default) | Agent calls `POST /secrets/retrieve/<token>`. Same call repeated within ~5 min returns the same value. |
+| Explicit consume path | Agent appends `?consume=true` to commit a one-shot read. Response includes `consumed: true`. |
+| Stuck-consumer event | Automatic. If a submission isn't consumed within 60s, a `[secret-drop-stuck]` system message routes to the bound topic's agent session. |
+
+## Deferred (Tracked Follow-ups)
+
+- Configurable grace period per-request (currently a hard-coded 60s
+  constant). Will be added when a real need surfaces.
+- Updating the bridge script in the parallel
+  `scripts/telegram-history-backfill.mjs` PR to read non-destructively
+  by default, parse first, and only consume after a successful parse.
+  That refactor lives in a separate commit after this PR lands.