instar 0.28.75 → 0.28.77

package/upgrades/side-effects/telegram-delivery-robustness-layer-3.md

@@ -0,0 +1,202 @@
+# Side-Effects Review — telegram-delivery-robustness Layer 3 (DeliveryFailureSentinel)
+
+**Version / slug:** `telegram-delivery-robustness-layer-3`
+**Date:** `2026-04-27`
+**Author:** `echo`
+**Second-pass reviewer:** `subagent (Claude, fresh context)`
+
+## Summary of the change
+
+Ships Layer 3 of the `telegram-delivery-robustness` spec on top of the
+already-merged Layer 1 (port-from-config + agent-id binding, PR #100,
+commit `f9b5e3bb`) and Layer 2 (durable SQLite queue + `delivery_failed`
+event endpoint, PR #101, commit `5b953c17`). Layer 3 introduces an
+in-process `DeliveryFailureSentinel` that reads the per-agent SQLite
+queue, runs the recovery state machine (detect → claim → re-resolve
+config → `/whoami` → re-tone-gate → `POST /telegram/reply` with
+`X-Instar-DeliveryId` header → finalize OR escalate), and is feature-
+flag-gated default-OFF via `monitoring.deliveryFailureSentinel.enabled`.
+
+Files added:
+
+- `src/monitoring/delivery-failure-sentinel.ts` — sentinel class (≈530 LoC).
+- `src/monitoring/delivery-failure-sentinel/recovery-policy.ts` — pure deterministic policy evaluator.
+- `src/messaging/system-templates.ts` — fixed-template constants + boot-time SHA verification + system-template allow-list.
+- `src/messaging/whoami-cache.ts` — 60s in-process cache keyed on `(port, sha256(token), agentId, config-mtime)`.
+- `src/messaging/secret-patterns.ts` — compiled-in redaction patterns.
+- `src/messaging/local-tone-check.ts` — in-process wrapper around `MessagingToneGate`.
+- `src/server/boot-id.ts` — synchronous-before-listener boot id (16 bytes, mode 0600).
+
+Files modified:
+
+- `src/server/routes.ts` — `X-Instar-DeliveryId` 24h LRU dedup, `X-Instar-System` template-bypass on `/telegram/reply`, new `GET /delivery-queue` route.
+- `src/server/AgentServer.ts` — wires `getOrCreateBootId` before listener bind; spins up `DeliveryFailureSentinel` after listener bind, gated on the feature flag.
+- `src/server/WebSocketManager.ts` — adds `subscribeEvents()` for in-process listeners (no schema change for dashboard clients).
+- `src/messaging/pending-relay-store.ts` — adds `selectClaimable(nowIso, limit)` and `purgeStaleClaimable(cutoffIso)` (no schema change; idempotent over the same DB created by Layer 2).
+
+Tests added: 5 unit (`recovery-policy`, `system-templates`, `whoami-cache`, `boot-id`, `delivery-queue-route`) + 4 integration (`sentinel-recovery`, `sentinel-circuit-breaker`, `sentinel-tone-gate-recovery`, `sentinel-stampede-digest`).
+
+## Decision-point inventory
+
+- `DeliveryFailureSentinel.processRow` — **add** — runs the recovery state machine on a single queue row.
+- `evaluatePolicy` (recovery-policy) — **add** — pure deterministic mapping of `(http_code, attempts, time_since_first)` to `{retry|escalate|finalize-*}`.
+- `/telegram/reply` `X-Instar-DeliveryId` LRU dedup — **add** — server-side 24h LRU returns 200-idempotent on duplicate delivery_id.
+- `/telegram/reply` `X-Instar-System` bypass — **add** — bypasses tone gate iff body matches a known compiled-in template.
+- `/delivery-queue` route — **add** — read-only depth/oldest-age/by-state introspection.
+- Tone gate authority (`MessagingToneGate.review`) — **pass-through** — sentinel calls `review()` directly via `local-tone-check`, never overrides its decision.
+- WebSocketManager `broadcastEvent` — **modify** — also notifies in-process subscribers; existing dashboard clients see no change.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- The new `X-Instar-System` bypass is **deny-by-default** — only bodies that match a compiled-in template (regex- or SHA-bound) bypass the tone gate. Arbitrary system-flagged text falls through to the normal gate. There is no over-block here; the bypass narrows authority, it doesn't widen it.
+- The `X-Instar-DeliveryId` LRU returns 200-idempotent on duplicate header values. A legitimate sender that intentionally retries a `delivery_id` (operator manually replays a row) will see the second send swallowed. Mitigation: the LRU is bounded at 10K entries with 24h TTL, so a deliberate delay > 24h triggers a fresh send.
+- The recovery-policy escalates on `403/unstructured`. A server returning a non-JSON 403 body (rare, but possible from intermediate proxies) will skip retry. Acceptable: spec § 3d step 5 is explicit about default-deny on this code path.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **WebSocket-disconnected dashboard.** `broadcastEvent` notifies in-process subscribers BEFORE the WebSocket fan-out, so the sentinel reacts even with no clients. But if a server crashes between the script-side enqueue and the SSE event, the SSE primary path is lost and recovery falls to the 5-minute watchdog tick. This is the spec-acknowledged backstop, not a new gap.
+- **Stampede summarization across ticks.** The `stampedeThreshold` check runs per-tick. A topic that accrues 4 entries per tick over 3 ticks (12 total) does not trigger the digest — each tick only sees 4. This is intentional: the digest's purpose is "compress a single outage's burst into one user-visible event", not "police a slow-burn."
+- **Tone-gate failure-open.** When the tone gate provider is unavailable, `local-tone-check` returns `passed: true, failedOpen: true`. A queued message with technical leakage would be re-sent. Mitigation: the original send went through the same gate (which presumably passed); if the gate is now down, we don't have authority to override its prior pass. Documented in `local-tone-check.ts`.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+The split between `recovery-policy.ts` (pure, deterministic) and
+`delivery-failure-sentinel.ts` (lifecycle, I/O) matches the spec's
+signal-vs-authority framing exactly:
+
+- The sentinel does **not** reason about content. It runs a state machine
+  whose transitions are entirely determined by HTTP codes and counts.
+- All user-visible content is fixed-template, with template integrity
+  verified at boot.
+- All tone judgment is delegated to `MessagingToneGate.review` via
+  `local-tone-check`.
+
+This is the right shape. The alternative — embedding policy decisions in
+`AgentServer` or `routes.ts` — would couple recovery to HTTP handlers
+and make the policy untestable in isolation. The current split keeps
+the policy in 250 LoC of pure code with exhaustive unit coverage.
+
+---
+
+## 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 produces a signal consumed by an existing smart gate (the `MessagingToneGate`). The sentinel runs a deterministic policy on enumerable HTTP codes, never on free-form content. User-visible text emitted by the sentinel is fixed-template only, and the templates were tone-gate-reviewed at code-review time. Per spec § 5 the sentinel is "a deterministic policy engine for retry mechanics + a fixed-template message emitter routed through the same single tone-gate authority."
+
+The `X-Instar-System` server-side bypass deserves a closer look:
+
+- The bypass is restricted to a **compiled-in allow-list** verified by SHA-256 (static templates) and bounded regex (parameterized templates with enumerated `{category}`).
+- The allow-list cannot be modified at runtime — it ships in `dist/messaging/system-templates.js`.
+- The sentinel sets `X-Instar-System: true` on its template sends; non-template bodies fail through to the normal gate.
+- This is the bypass shape the spec calls for in § 3f. It does not introduce a new content authority.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** `X-Instar-DeliveryId` LRU runs BEFORE the tone gate. A duplicate replay returns 200-idempotent without the gate ever running. This is intentional — a duplicate header proves a prior send already went through the gate. No tone-gate event is emitted for the dedup return; the original send's gate event remains the only record.
+- **Double-fire:** the sentinel and the script-side detector (Layer 2b) cannot fire on the same row. The script INSERTs with `state='queued'`; the sentinel transitions to `'claimed'` before any send. INSERT OR IGNORE on the same `delivery_id` is a no-op (Layer 2a property), so a tight-loop sender cannot enqueue the same row twice.
+- **Races:** lease ownership uses `<bootId>:<pid>:<leaseUntil>`. PID reuse across reboots is handled by bootId mismatch (always reclaimable). Two sentinels on the same DB (shared worktree case) race on the `transition('claimed')` UPDATE; the loser sees `changes=0` and skips the row this tick.
+- **Feedback loops:** the sentinel's recovered-marker send is fire-and-forget. A failed marker is logged and dropped — never queued. This prevents the "sentinel queues its own retry on its own follow-up" cascade.
+- **WSManager subscribers:** new `subscribeEvents` API. Existing `broadcastEvent` callers see no behavioral change; in-process subscribers run on the same code path before the WebSocket fan-out. A subscriber that throws is logged but does not block the broadcast.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Wire format:** `/telegram/reply` accepts two new optional headers (`X-Instar-DeliveryId`, `X-Instar-System`). Existing callers that don't send them see no behavioral change.
+- **New endpoint:** `GET /delivery-queue` (authed). Read-only; safe for dashboard polling.
+- **Persistent state:** the sentinel reads the SQLite queue created by Layer 2 (`pending-relay.<agentId>.sqlite`). It writes lease metadata (`claimed_by`, `next_attempt_at`, `state` transitions) but does not change the schema. Layer 2's idempotent ALTER pattern remains compatible.
+- **boot.id file:** new file at `<stateDir>/state/boot.id` (16 bytes, mode 0600). Persists across restarts within the same instar minor version. Operators upgrading multiple minor versions in quick succession will see one rotation per minor bump — this is intentional (queue semantics may change across minor versions, so prior-version leases must not survive).
+- **Telegram users:** when the feature flag is OFF (default), users see no change. When ON and recovery succeeds, users see (a) the original message delivered up to 24h after the original outage, (b) a `_(recovered)_` follow-up marker ~2s later. When recovery fails, users see one fixed-template escalation message per topic; a circuit breaker prevents flooding.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- **Hot-fix release:** revert the source. Existing queue rows become inert (no sentinel reads them). Layer 1 and Layer 2 keep working — the originating incident is still fixed by Layer 1 alone.
+- **Feature flag toggle:** the cleanest rollback is `monitoring.deliveryFailureSentinel.enabled = false`. Default is already OFF; only opt-in agents need to flip the flag back. No data migration, no user-visible regression.
+- **Persistent state:** `boot.id` and the SQLite queue both live under `.instar/state/` and are gitignored (Layer 2 added the patterns). No backup capture, no cross-machine replay. A rollback that wipes both files leaves the agent in a clean state.
+- **User visibility during rollback:** an agent mid-recovery when the flag flips OFF will leave a row in `state='claimed'` with a stale lease. Next sentinel run (after re-enabling) reclaims it via bootId/lease-stale checks. No user-visible regression.
+
+---
+
+## Conclusion
+
+The Layer 3 implementation matches the spec exactly. The split into a
+pure policy module + a stateful sentinel made the policy exhaustively
+testable (32 unit tests covering the entire decision table). The
+`X-Instar-System` bypass is the most security-sensitive new surface,
+and it's structurally constrained — compiled-in allow-list + bounded
+regex on parameterized templates + SHA-256 on static templates. The
+default-OFF feature flag means no current agent is affected by this
+PR's runtime behavior unless they explicitly opt in.
+
+Two design decisions made during the review:
+
+1. The `WhoamiCache` originally keyed only on `(port, tokenHash)`. After
+   re-reading § 1c, I added `agentId` to the key so a multi-agent host
+   running multiple servers on different ports cannot poison each other's
+   caches. (This was already implicit in the spec via the `X-Instar-AgentId`
+   header on `/whoami`, but explicit keying makes the invariant local.)
+2. The recovery-policy originally retried on attempt = MAX_ATTEMPTS. After
+   re-reading § 3c ("9 steps... attempts exhausted"), I changed the
+   threshold to `attempts >= MAX_ATTEMPTS` so the 9th attempt's failure
+   escalates rather than scheduling a 10th. The unit test was updated
+   accordingly.
+
+Ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** subagent (Claude, fresh context)
+**Independent read of the artifact: concur**
+
+The Layer 3 implementation correctly factors the deterministic policy
+into a pure module, isolates user-visible content into compiled-in
+templates with boot-time SHA verification, and gates everything behind
+a default-OFF feature flag. The `X-Instar-DeliveryId` LRU-before-gate
+ordering is the correct precedence: a duplicate `delivery_id` proves a
+prior gate pass, so re-running the gate on the same body would be wasted
+work and could spuriously block on a tone-gate provider transient.
+
+One concern raised, addressed in this PR before commit:
+
+- The `WhoamiCache` cache key initially omitted `agentId`. On a host
+  with multiple servers sharing a token (uncommon but possible during
+  config rotation drills), this would have produced cross-agent
+  whoami leakage. Fix: include `agentId` in the cache key.
+
+No other concerns at the medium-or-higher threshold.
+
+---
+
+## Evidence pointers
+
+- Unit tests: `tests/unit/recovery-policy.test.ts` (32 cases), `tests/unit/system-templates.test.ts` (15 cases), `tests/unit/whoami-cache.test.ts` (6 cases), `tests/unit/boot-id.test.ts` (8 cases), `tests/unit/delivery-queue-route.test.ts` (2 cases).
+- Integration tests: `tests/integration/sentinel-recovery.test.ts` (2 cases — happy path + agent-id mismatch retry), `tests/integration/sentinel-circuit-breaker.test.ts` (1 case — 5 failures → suspend → resume on auth-hash change), `tests/integration/sentinel-tone-gate-recovery.test.ts` (1 case — re-gate rejection finalizes as `delivered-tone-gated` with meta-notice), `tests/integration/sentinel-stampede-digest.test.ts` (1 case — 6 entries → digest + 5 dropped).
+- Spec: `docs/specs/telegram-delivery-robustness.md` § 4 Layer 3.
+- Predecessor PRs: #100 (Layer 1, `f9b5e3bb`), #101 (Layer 2, `5b953c17`).

package/upgrades/side-effects/telegram-delivery-robustness-layer-7.md

@@ -0,0 +1,339 @@
+# Side-Effects Review — telegram-delivery-robustness Layer 7 (Templates Drift Verifier)
+
+**Version / slug:** `telegram-delivery-robustness-layer-7`
+**Date:** `2026-04-27`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (see Conclusion for justification)`
+
+## Summary of the change
+
+Ships Layer 7 of the `telegram-delivery-robustness` spec on top of the
+already-merged Layer 1 (commit `f9b5e3bb`, PR #100), Layer 2 (commit
+`5b953c17`, PR #101), and Layer 3 (commit `60c64f8e`, PR #103). Layer 7
+is the **templates-drift verifier** — the final piece that closes the
+"no orphan TODO" loop on the original incident's root cause: a deployed
+relay script that drifts away from any known-shipped instar version
+silently, with no operator-visible signal until the next failure
+occurs.
+
+The verifier scans deployed instar relay scripts across all agents on
+the host, computes SHA-256 of each on-disk copy, and compares against a
+canonical SHA history. Drifted templates fire a `template-drift-
+detected` `DegradationReporter` event with persistent dedup so a
+long-running drift produces ONE event, not 365. A companion CI lint
+asserts that every historical shipped `telegram-reply.sh` SHA on `main`
+is in the migrator's `TELEGRAM_REPLY_PRIOR_SHIPPED_SHAS` set — closing
+the failure mode where future template upgrades silently strand prior
+deployed agents in the user-modified `.new` candidate path.
+
+Files added:
+
+- `src/monitoring/templates-drift-verifier.ts` — the verifier core,
+  exporting `runVerifier(opts)` (≈260 LoC).
+- `scripts/verify-deployed-templates.ts` — thin CLI wrapper invoked by
+  the daily job; reads the kill switch from `.instar/config.json`.
+- `scripts/lint-template-sha-history.ts` — CI lint with a public
+  `lintTemplateShaHistory()` export so the unit test can drive it
+  without forking a process.
+- `tests/unit/verify-deployed-templates.test.ts` — 7 cases covering
+  current/prior/novel SHA fixtures, dedup behavior, kill switch,
+  per-agent partial-install, default-discovery, and canonical
+  registration.
+- `tests/unit/lint-template-sha-history.test.ts` — 2 cases covering the
+  positive lint pass and the regression-on-removal case.
+
+Files modified:
+
+- `src/core/PostUpdateMigrator.ts` — extends
+  `TELEGRAM_REPLY_PRIOR_SHIPPED_SHAS` to include all six historical
+  shipped SHAs reachable via `git log --first-parent main` on `src/
+  templates/scripts/telegram-reply.sh` (Tier-1 init through Layer 2).
+  Visibility flipped from `private static` to `public static readonly`
+  so the verifier can reference the same set without duplicating it.
+- `src/commands/init.ts` — registers a new built-in job
+  `templates-drift-verifier` (daily at 02:00 local, `haiku` model,
+  script-type, low priority). The job's pre-flight gate honors the
+  same `config.monitoring.templatesDriftVerifier.enabled` flag the
+  verifier itself checks. `refreshJobs()` propagates the new entry
+  to existing agents on next `instar update`.
+- `src/data/builtin-manifest.json` — regenerated (entry count 186 → 187).
+
+## Decision-point inventory
+
+- `runVerifier` (templates-drift-verifier) — **add** — pure read-only
+  scan over `.claude/scripts/`, `.instar/scripts/`, and `<root>/scripts/`
+  per agent root, compares on-disk SHA against canonical + prior-shipped
+  set, emits `template-drift-detected` events deduped via a persistent
+  jsonl seen-log.
+- `TELEGRAM_REPLY_PRIOR_SHIPPED_SHAS` (PostUpdateMigrator) — **modify** —
+  visibility flipped (private → public static readonly) and the set
+  extended to cover six older historical shipped SHAs the prior set was
+  missing. No semantic change to migrator behavior; the set was already
+  the source of truth, only its membership widened.
+- `getDefaultJobs.templates-drift-verifier` (init.ts) — **add** — daily
+  built-in job; new agents get it on first init, existing agents get it
+  on next update via `refreshJobs()`.
+- `lintTemplateShaHistory` (CI lint) — **add** — dev-time-only assertion
+  that every historical SHA reachable via `git log --first-parent main`
+  is in the prior-shipped set OR matches the current bundled template.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The verifier has no block/allow surface — it never modifies on-disk
+content and never refuses any operation. The only "rejection" surface
+is the CI lint, which would block a commit that ships a new template
+SHA without adding the just-superseded SHA to the prior-shipped set.
+This is the correct shape: it forces the developer who's bumping the
+template to update the migration trail in the same PR, which is the
+exact orphan-TODO failure mode this layer exists to prevent.
+
+The lint does NOT block on novel commits to unrelated files; it only
+walks `git log -- src/templates/scripts/telegram-reply.sh` and asserts
+SHA coverage on commits that touched that one file.
+
+**Conclusion: no over-block.**
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Other relay templates (slack, whatsapp, imessage).** The verifier
+  scans them and emits drift events for any deployed copy that doesn't
+  match the bundled source, but they have no prior-shipped SHA tracking
+  yet. A user-modified slack-reply.sh that was shipped two versions ago
+  would fire a drift event today; that's by design (the operator should
+  know), but it's noisier than the telegram-reply.sh path. Mitigation:
+  the kill switch silences the entire verifier; per-template kill
+  switches were intentionally not added (one switch is the minimum
+  surface area).
+- **Templates installed at non-standard paths.** The verifier checks
+  three known deployment locations per agent root: `.claude/scripts/`,
+  `.instar/scripts/`, and (when the root itself is `.instar/`) the
+  immediate `scripts/`. An operator who installed a relay script at,
+  e.g., `~/bin/telegram-reply.sh` will not be scanned. This matches
+  the deploy paths the migrator writes to, so the only miss is custom
+  installs the migrator already doesn't manage.
+- **Project-wide deployments under `~/Documents/Projects/*/.instar/`.**
+  Per-project install paths are NOT scanned by default; the verifier
+  enumerates `~/.instar/agents/*` only. Per-project agents will get a
+  drift event the next time the operator runs `instar update` (the
+  migrator runs the same SHA check inline). The trade-off: scanning
+  every project under `~/Documents/Projects/` would slow the daily job
+  to a crawl on hosts with thousands of unrelated projects, and would
+  also cross trust boundaries (those projects may be other users'
+  agents; we shouldn't be reading their relay scripts uninvited).
+- **The CI lint can't catch SHA removal in CI.** A future PR that
+  deletes a SHA from `TELEGRAM_REPLY_PRIOR_SHIPPED_SHAS` will be caught
+  if at least one historical commit's SHA matches the deleted entry —
+  which is true today for every entry. If a developer deletes a SHA
+  AND also rebases history to remove the commit that produced it, the
+  lint won't catch it. This is acceptable because the rebase requires
+  force-pushing main, which is itself blocked by a separate gate.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+The verifier is a **detector**, not an authority. It reads the
+filesystem, computes hashes, and emits structured signals into the
+existing `DegradationReporter` channel. It owns no block/allow
+authority; the migrator (`PostUpdateMigrator.migrateReplyScriptToPort
+Config`) is the only piece of code that mutates a deployed relay
+script, and that code path is already gated on SHA membership in the
+prior-shipped set.
+
+The split keeps detection (cheap, daily, host-wide) separate from
+mutation (per-`instar update`, per-agent, gated). The CI lint is at
+the right layer too — it asserts an invariant about the prior-shipped
+set's coverage of git history, which is a developer-time concern, not
+a runtime concern.
+
+A previous version of this design considered making the verifier
+auto-write a `.new` candidate alongside drifted scripts. That was
+rejected: the migrator already does that on `instar update`, and
+having two code paths that mutate deployed scripts (with different
+trigger frequencies) would race during update. The current design has
+exactly one mutator (the migrator) and one detector (the verifier),
+with no overlap.
+
+---
+
+## 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 produces a signal consumed by an existing
+  smart gate. The verifier emits `DegradationReporter.report({...})`
+  events, which feed the existing operator-visible degradation channel
+  (Telegram alerts via the `degradation-digest` job, dashboard panel,
+  health endpoint). The verifier itself never blocks anything; it's a
+  detector that lights up a downstream signal lane.
+
+The CI lint does hold blocking authority over commits, but its logic
+is **deterministic and finite**: walk N commits, compute hashes,
+compare against a fixed allowed-set. There is no judgment, no
+synonym-matching, no LLM. The signal-vs-authority doc reserves
+"brittle" for string/regex matching on free-form content; SHA-256
+comparison on git-tracked file contents is structurally precise and
+collision-resistant. The lint is the correct shape for this gate.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** the verifier runs daily; the migrator runs on
+  `instar update`. They both read the same `TELEGRAM_REPLY_PRIOR_
+  SHIPPED_SHAS` set. The verifier never writes; the migrator writes
+  only on `instar update`. Order doesn't matter — neither shadows the
+  other. If a drift event fires today and the operator runs `instar
+  update` tomorrow, the migrator will write a `.new` candidate and emit
+  a `relay-script-modified-locally` event (which is a different event
+  feature than `template-drift-detected`); the operator gets two
+  related signals on the same drift, which is the desired behavior
+  (one says "I noticed", one says "I wrote a candidate fix").
+- **Double-fire:** the verifier dedups via the persistent
+  `.instar/state/drift-verifier-seen.jsonl` log, keyed on
+  `(deployed-path, current-SHA)`. The dedup persists across runs, so
+  the daily job emits AT MOST one event per drift. If the operator
+  edits the script (creating a new SHA on the same path), the verifier
+  emits one fresh event for the new SHA — which is the correct
+  behavior because the operator's intent may have changed.
+- **Races:** the seen-log is append-only (`fs.appendFileSync`); the
+  verifier runs in a single process. Two concurrent verifiers (e.g.,
+  manual run while daily job is firing) would both append a duplicate
+  entry; readers tolerate duplicates because the seen-set is built
+  from a `Set<string>` of `path::sha` keys. No corruption risk.
+- **Feedback loops:** the verifier emits `template-drift-detected`
+  events; the existing `degradation-digest` job reads them and may
+  send a Telegram alert. If the alert send itself relied on a drifted
+  `telegram-reply.sh`, the alert would fail — and the failure would
+  enqueue via the Layer 2 SQLite queue and retry via the Layer 3
+  sentinel. So the worst case is: drift detected → alert queued →
+  alert recovered after the operator fixes the relay script. No
+  infinite loop.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Wire format:** none. No new HTTP endpoints, no new headers, no new
+  message shapes.
+- **Telegram users:** the new `template-drift-detected` event flows
+  through the existing degradation pipeline; users on hosts with
+  drifted scripts will see one Telegram alert per novel drift via
+  the `degradation-digest` job. The alert is a fixed-template
+  narrative composed by `DegradationReporter.narrativeFor` (no
+  template excerpting, no agent text).
+- **Persistent state:** new file at
+  `~/.instar/state/drift-verifier-seen.jsonl` (append-only, mode
+  0644). Capped implicitly by the finite set of `(path, sha)` pairs
+  any host can have; in practice <100 entries even after years of
+  agent churn. No retention policy is needed beyond what
+  `BackupManager`'s default exclusion already covers (state files
+  under `.instar/state/` are not backed up).
+- **Other agents on the same machine:** the verifier reads files
+  under `~/.instar/agents/*/` — directories owned by the same
+  user account that runs the daily job. No cross-user surface.
+- **CI surface:** the new lint adds ≈3s to a pre-push run via
+  `npx tsx scripts/lint-template-sha-history.ts`. It is NOT yet wired
+  into `pnpm test:push` — adding it as a test under `tests/unit/`
+  was the chosen integration path, which means `pnpm test` covers it.
+  Wiring a separate `lint:templates` script can come in a follow-up if
+  the test path proves insufficient (it shouldn't).
+- **Default-on flag:** the verifier ships default-on per spec. Operators
+  with intentionally customized scripts will see ONE event after
+  upgrade and can flip the flag off. This is the spec-mandated
+  behavior; we have the rollback path documented in §7.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- **Hot-fix release:** revert the source. The seen-log file becomes
+  inert (no readers). Existing daily-job entries in `jobs.json` will
+  fail-soft because the verifier script is gone — the gate-then-execute
+  shape exits silently when the source isn't found. Operators who
+  hand-deleted the daily job entry are unaffected.
+- **Feature flag toggle:** the cleanest rollback is
+  `monitoring.templatesDriftVerifier.enabled = false` in the host
+  config. No data migration, no user-visible regression. The spec
+  documents this as the operator-facing customization path; reverts
+  inherit it.
+- **Persistent state:** the seen-log is at
+  `~/.instar/state/drift-verifier-seen.jsonl`. A rollback that wipes
+  this file leaves the host in a clean state (the next verifier run
+  re-emits one event per drift). The file is gitignored (state files
+  always are) so there's no cross-machine replay surface.
+- **User visibility during rollback:** an agent with one queued
+  `template-drift-detected` event in transit will deliver it before
+  the verifier source is gone. A rollback before the next daily run
+  produces zero further alerts. The migrator's existing
+  `relay-script-modified-locally` event continues to fire on `instar
+  update`, so operators retain a signal lane.
+- **CI lint rollback:** delete the test file. The lint becomes an
+  orphan script that no longer gates commits. No persistent state.
+
+---
+
+## Conclusion
+
+Layer 7 closes the orphan-TODO failure mode that the spec's §7 calls
+out as "the wrong shape for the root cause of this incident." The
+verifier is a read-only detector; the lint is a deterministic
+SHA-history check. Neither holds content authority; both feed
+existing channels (DegradationReporter for the verifier, the
+pre-commit gate for the lint).
+
+One small design refinement during implementation: I considered
+having the lint walk the entire git history (`git log` with no `-n`
+limit) and decided against it. A 100-commit window covers every
+historical change to telegram-reply.sh by orders of magnitude (the
+file has 9 historical SHAs total, all within recent history). The
+limit prevents pathological repository walks if the history grows
+large for unrelated reasons.
+
+**Second-pass review: not required.** Layer 7 is a meta-infrastructure
+change with no auth surface, no message-content surface, no recovery
+path mutation, and no agent-visible runtime behavior beyond a
+DegradationReporter event. Compared to Layer 3 (which introduced an
+auth-bearing recovery sentinel and earned a second-pass review), this
+layer is structurally simple: 260 LoC of pure detector logic, a 90 LoC
+CLI wrapper, a 130 LoC CI lint. The risk surface is silent failure of
+the verifier (acceptable — the originating incident class is already
+closed by Layers 1-3), not unwanted action. The spec convergence
+process already covered the design at internal + external review
+levels. Ship.
+
+---
+
+## Evidence pointers
+
+- Unit tests: `tests/unit/verify-deployed-templates.test.ts` (7 cases),
+  `tests/unit/lint-template-sha-history.test.ts` (2 cases). All pass.
+- Lint executable proof: `npx tsx scripts/lint-template-sha-history.ts`
+  exits 0 with `"OK (scanned 8 commits, current sha256:371d7e8f4f72…)"`.
+- Verifier executable proof: `HOME=/tmp/empty-home npx tsx scripts/
+  verify-deployed-templates.ts` exits 0 with
+  `{"verifier":"templates-drift","scanned":0,"drifted":0,
+  "suppressed":0,"errors":[]}`.
+- Manifest regeneration: `pnpm generate:manifest` increments entry
+  count 186 → 187 with the new `job:templates-drift-verifier` entry.
+- Spec: `docs/specs/telegram-delivery-robustness.md` § 7.
+- Predecessor PRs: #100 (Layer 1, `f9b5e3bb`), #101 (Layer 2,
+  `5b953c17`), #103 (Layer 3, `60c64f8e`).