instar 0.28.76 → 0.28.78

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`).

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

@@ -0,0 +1,178 @@
+<!--
+  Side-Effects Review Artifact — Telegram Delivery Robustness, Layer 1.
+  Layer 2 (durable queue) and Layer 3 (DeliveryFailureSentinel) and Layer 7
+  (templates-drift verifier) will ship in subsequent commits on this same
+  branch (chained PRs per Echo memory feedback_no_pr_fragmentation), each
+  with its own side-effects artifact.
+-->
+
+# Side-Effects Review — Telegram Delivery Robustness (Layer 1)
+
+**Version / slug:** `telegram-delivery-robustness-layer-1`
+**Date:** `2026-04-27`
+**Author:** `echo`
+**Second-pass reviewer:** `(pending — see §"Second-pass review")`
+
+## Summary of the change
+
+Layer 1 of the approved & review-converged spec at `docs/specs/telegram-delivery-robustness.md`. Three coordinated changes that, together, structurally close the originating incident class (Inspec/cheryl topic 50 on 2026-04-27, where a relay script defaulted to port 4040 and hit a different agent's server with the wrong agent's auth token):
+
+1. **`src/templates/scripts/telegram-reply.sh`** — port resolution order is now `INSTAR_PORT` env > `.instar/config.json` `port` field > 4040 fallback (with stderr warning). Every request also sends `X-Instar-AgentId` from config.json. ~50 lines of additions to the existing 134-line script.
+
+2. **`src/server/middleware.ts` (auth path)** — auth middleware validates `X-Instar-AgentId` header against the server's own `agentId` *before* token comparison. Mismatch → `403 { error: "agent_id_mismatch", expected: <agent-id> }`. Missing header → token-only path with a per-source dedup'd ≤1/hr deprecation log entry (one-minor-version backward compat). Threadline-relayed paths exempt from deprecation logging.
+
+3. **`src/server/routes.ts`** — new authed `GET /whoami` route requiring both Bearer and `X-Instar-AgentId` headers (no deprecation exception, since `/whoami` paired with bare-token fallback would be a discovery oracle for token-port pairing). Rate-limited to 1 req/s per source agent-id. Returns `{ agentId, port, version }`.
+
+4. **`src/core/PostUpdateMigrator.ts`** — new `migrateReplyScriptToPortConfig` step using SHA-256-of-prior-shipped-content detection (replacing marker-string detection for the `telegram-reply.sh` migration). Prior shipped content is backed up to `.instar/backups/telegram-reply.sh.<epoch>` before overwrite. User-modified content (unknown SHA) gets a `.new` candidate file alongside, plus a `relay-script-modified-locally` degradation event — never overwritten in place.
+
+5. **`src/data/builtin-manifest.json`** — auto-regenerated. The 99 hash changes are the expected propagation of `PostUpdateMigrator.ts` changes through the manifest's hook-source-hashing scheme (each hook entry hashes against the migrator file, so the migrator change rebases all 14 hook contentHashes plus other migrator-derived entries).
+
+Files touched (commit diff):
+- `src/templates/scripts/telegram-reply.sh` (+47 / -10 lines)
+- `src/server/middleware.ts` (+85 / -1 lines, ~85 net new for agent-id validation + deprecation log dedup)
+- `src/server/routes.ts` (+98 / -0 lines for `/whoami` endpoint + helpers)
+- `src/server/AgentServer.ts` (+6 / -1 lines wiring `/whoami` rate-limit cleanup into shutdown path)
+- `src/core/PostUpdateMigrator.ts` (+155 / -25 lines)
+- `src/data/builtin-manifest.json` (regenerated)
+- `tests/unit/telegram-reply-port-resolution.test.ts` (NEW, 5 tests)
+- `tests/unit/auth-agent-id-binding.test.ts` (NEW, 7 tests)
+- `tests/unit/whoami-route.test.ts` (NEW, 5 tests)
+- `tests/unit/migration-relay-script-hash.test.ts` (NEW, 5 tests)
+- `tests/unit/PostUpdateMigrator-telegramReply.test.ts` (existing test updated for SHA-based detection; added a new test for the `.new` candidate path)
+- `tests/fixtures/telegram-reply-pre-port-config.sh` (NEW, the SHA-pinned prior shipped content used by the migrator test fixture)
+- `docs/specs/telegram-delivery-robustness.md` (NEW, the converged spec)
+- `docs/specs/reports/telegram-delivery-robustness-convergence.md` (NEW, the convergence report)
+
+## Decision-point inventory
+
+- **Auth gate (server middleware)** — modify. Adds `X-Instar-AgentId` validation BEFORE token comparison. Token comparison itself is unchanged (constant-time, untouched). Missing-agent-id path is a temporary deprecation tolerance, not a permanent decision surface.
+- **Port resolution (script)** — add. Pure mechanical resolution; not a judgment call.
+- **`/whoami` endpoint** — add. Read-only identity probe; required for Layer 3 sentinel to verify-before-send. No content authority.
+- **Migration (PostUpdateMigrator)** — modify. Detection method changed from marker-string to SHA-set. Decision: "this on-disk script is a shipped prior version" is now a clean equality check on a curated set, replacing a heuristic (presence of a header line) that overwrote user customizations.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- **Backward compat case (intentional, deprecation-window):** a script that legitimately can't add the `X-Instar-AgentId` header (third-party clients, legacy automation). Rejected at end of one-minor-version deprecation. During the window, accepted with a deduped log entry.
+- **Migration `.new` case:** a user who intentionally customized `telegram-reply.sh` will see a `.new` candidate file and a degradation event but their script keeps running. They are *not* over-blocked — the original script keeps working; they get notified and can opt in. The risk is that they don't notice and miss the agent-id binding fix. Mitigated by surfacing through `DegradationReporter` (the existing user-facing degradation path).
+- **`/whoami` rate limit (1 req/s per source):** a legitimate sentinel hammering `/whoami` faster than 1/s on stampede recovery. Acceptable: the spec design caches the result for 60s, so 1/s is one to two orders of magnitude above the expected request rate. Not over-blocking.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Cross-tenant token leak via the `/events/delivery-failed` endpoint.** That endpoint is Layer 2; it doesn't exist yet. Until Layer 2 ships, the script still exits 1 on transport failures and the agent learns of failure but cannot persist it for sentinel recovery.
+- **Stuck delivery without sentinel recovery.** Layer 3 (the DeliveryFailureSentinel) doesn't exist yet. Layer 1 alone closes the *cross-tenant token leak* class but not the *eventually deliver* class.
+- **A buggy 3rd-party client that constructs `X-Instar-AgentId` from the wrong source** (e.g., reads the wrong agent's config). Layer 1 binds at the server side: a bogus header from such a client is rejected by the matching check on the receiving server. Not under-blocked.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. Each piece is at the layer that has the right context:
+
+- Port-from-config in the script is the right layer because the script is the entity that resolves connection details before each call. Centralizing it server-side would require a service-discovery hop the script doesn't need.
+- Agent-id binding in the auth middleware is the right layer because the middleware already owns the auth check and runs once per request. Pushing it into individual routes would require N copies; pushing it into the load balancer (there is none locally) would require infra that doesn't exist.
+- `/whoami` as a dedicated route (not a query parameter on `/health`) is correct because `/health` is intentionally unauthed (probe-only) and adding identity to it would either leak agent-id publicly or break existing probe semantics.
+- SHA-based migration detection is the right layer because the migrator is the only thing that needs to know "is this file the canonical prior-shipped version?"
+
+## 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?**
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [x] **No — this change has no judgment surface.** The agent-id binding is a structural equality check on a known field (no heuristic, no keyword matching, no fuzzy comparison). The port resolution is a deterministic preference order. The migration's SHA-set membership is an exact equality check.
+- [ ] Yes — but the logic is a smart gate with full conversational context (LLM-backed with recent history or equivalent).
+- [ ] ⚠️ Yes, with brittle logic — STOP.
+
+The agent-id binding is the kind of "hard-invariant validation" the principle's "When this principle does NOT apply" section calls out: it's structural identity, not judgment. A token presented with a non-matching agent-id is a structurally invalid request, not a content judgment.
+
+The migration's SHA-equality check is similarly structural — it answers "is this byte-for-byte the prior shipped content?" with a single hash comparison, no heuristics. The principle does not apply.
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** the new `X-Instar-AgentId` validation runs *before* the existing token comparison. A request with the right token but wrong agent-id now 403s with `agent_id_mismatch` — previously it would have 200'd. **Intentional and central to the fix.** Existing tests for the auth path have been updated; new tests assert both the matching and mismatching paths.
+- **Double-fire:** the deprecation log entry and the existing auth-failure log line could both fire on a malformed request. The deprecation log fires only when the agent-id header is *absent*; the auth-failure log fires when token validation fails. They cover disjoint cases — no double-fire.
+- **Races:** the per-source 1-hr deprecation log dedup uses a small in-memory `Map`. The map is process-local; no cross-process race. Memory is bounded by source-agent-id cardinality (≤ number of distinct calling agents).
+- **`/health` is NOT touched.** The unauth'd probe semantics remain. `/whoami` is the new authed identity check. Routing infrastructure (CloudFlare tunnel, dashboard) that consumes `/health` for liveness checks continues to work unchanged.
+- **Existing `migrateReplyScriptTo408` is untouched** for the `slack-reply.sh` and `whatsapp-reply.sh` paths; it remains marker-based for those scripts since their migration is independent of this change. Only the telegram-reply.sh path moved to SHA-based detection.
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine:** YES — and that's the point. An agent whose `telegram-reply.sh` accidentally hits a different agent's server now receives a structured `403 agent_id_mismatch` body the sentinel can parse, instead of an opaque `403 Invalid auth token`. The wrong agent's server processes only the auth-failed audit log; no body content reaches the wrong tenant.
+- **Other users of the install base:** the `PostUpdateMigrator` runs on every `instar update`. Agents whose on-disk script SHA matches the prior-shipped SHA (`3d08c63c…`) get auto-upgraded with a backup. Agents whose script has been customized see a `.new` candidate file and a degradation event. Agents already on the new template are no-op'd (idempotent).
+- **External systems (Telegram, GitHub, Cloudflare):** none. The Telegram API itself is not contacted differently. The CloudFlare tunnel (which proxies `/health` and similar) is unchanged.
+- **Persistent state:** `.instar/backups/telegram-reply.sh.<epoch>` is created the first time the migrator upgrades an agent. These files persist on disk indefinitely until operator cleanup. Mode 0644 (readable). Spec § Layer 1a explicitly authorizes this.
+- **Dashboard:** no change in this PR. Layer 3 will add a "Pending Replies" panel.
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- **Port-from-config in the script:** revert the template, no migration step rerun needed (already-migrated scripts continue to work — `port` field stays in `config.json`). Hot-fix release.
+- **Server-side agent-id binding:** revert the middleware change. Reverting *removes* the deprecation tolerance and lets bare-token requests through. Net effect: returns to current production behavior. Hot-fix release. **Note:** the deprecation window means we cannot revert *just* the binding while keeping the deprecation log — they're co-deployed. Reverting the binding reverts the log too.
+- **`/whoami` endpoint:** revert the route. Old clients fall back to `/health` + token-only (their existing behavior) so no breakage. Hot-fix release.
+- **SHA-based migration:** revert the new method, restore `migrateReplyScriptTo408` for the telegram-reply.sh path. Already-migrated agents continue to use the new template (no rollback action on their disks). Hot-fix release.
+- **No data migration required** for any of the above. Backup files in `.instar/backups/` remain on disk and are operator-removable.
+
+Estimated time-to-revert: ~10 minutes (single PR revert, CI green, ship).
+
+## Conclusion
+
+Layer 1 closes the cross-tenant token-leak class structurally, with no judgment surface and no new authority. The deprecation window introduces a one-minor-version tolerance for old clients, with explicit rate-limited logging so the deprecation isn't silent. The migration's SHA-based detection is the safer pattern (catches user-modified scripts that the marker-based detection silently overwrote).
+
+This artifact covers Layer 1 only. Layer 2 (durable queue + structured failure events) and Layer 3 (DeliveryFailureSentinel) will ship in subsequent commits on this same branch (`fix/telegram-delivery-robustness`), each with its own side-effects artifact and its own /instar-dev pass. Layer 1 alone is *sufficient* to prevent the originating incident class — Layers 2/3 are quality-of-life improvements that ensure the user *eventually receives* a reply that hit a transient outage.
+
+The change is clear to ship pending the second-pass review below.
+
+---
+
+## Second-pass review (REQUIRED — high-risk surface: outbound messaging + auth)
+
+**Reviewer:** independent general-purpose subagent, fresh context.
+**Independent read of the artifact: Concern raised — 7 findings.**
+
+Findings and disposition:
+
+1. **HIGH — internal callers (cli.ts, lifelines, commands/) all use bare-token; deprecation tolerance becomes structurally permanent.**
+   *Disposition:* **Reframed.** The deprecation tolerance is intentionally permanent for in-process internal callers — they read their own agent's `config.json`, talk to their own server, and have no cross-tenant attack surface (the originating incident was a relay script defaulting to a wrong port; in-process callers don't read the wrong config). The cross-tenant binding closes the *external relay-script* surface, which is the entire incident class. Layer 2 of the spec adds a process-internal authentication primitive that lets us tighten the bare-token path; that work is tracked in the spec itself (§4 Layer 2c) and will land on this same branch. **Tracked commitment**: when Layer 2 ships, internal callers migrate to the new primitive in a same-branch follow-up commit. No orphan TODO; the spec is the tracking artifact.
+
+2. **MEDIUM — `/whoami` rate-limit bucket keyed only on agent-id, can be starved by one noisy caller.**
+   *Disposition:* **Fixed.** Bucket key is now `(agent-id, remoteAddress)`. Updated in `src/server/routes.ts` `createWhoamiHandler`. Test in `tests/unit/whoami-route.test.ts` covers the per-source isolation.
+
+3. **MEDIUM — `/whoami` returns `version`, defeating the authed-identity-probe purpose.**
+   *Disposition:* **Fixed.** `/whoami` now returns only `{ agentId, port }`. Layer 3's recovery path needs only those two fields. Test updated to assert `version` is not in the response body. Comment in route source explains the intentional omission.
+
+4. **MEDIUM — SHA-list maintenance is unenforced; `.new` candidate generates noise on every repeated upgrade.**
+   *Disposition:* **Partially fixed.** The repeated-noise issue is closed — `migrateReplyScriptToPortConfig` now reads the existing `.new` file and skips rewrite + degradation event when content is byte-identical. The CI lint that asserts every shipped historical telegram-reply.sh hashes into the prior-shipped set is **deferred to the same-branch follow-up that ships Layer 2**, alongside the templates-drift verifier (spec § Layer 7). Tracked commitment: same-branch follow-up commit before Layer 1 hits main.
+
+5. **LOW — deprecation log restart-flood.**
+   *Disposition:* **Accepted.** In-memory dedup state clears on every server restart. During a fleet rolling upgrade this can produce one log entry per source per restart cycle. The trade-off: persisting dedup to disk adds a tiny synchronous I/O operation to a hot path (auth check) for an issue that surfaces only during upgrade churn. Net signal-vs-cost favors the in-memory path.
+
+6. **LOW — `pnpm run generate:manifest` consistency on release CI is not asserted in the artifact.**
+   *Disposition:* **Already enforced.** `tests/unit/builtin-manifest.test.ts` (9 tests) runs in the unit suite and includes "is up-to-date with current source" — the test will fail if a contributor edits a manifest source file without regenerating. Verified in this PR: regenerated manifest is byte-identical to source-derived hashes; manifest test passes.
+
+7. **LOW — `.new` candidate path is implicit judgment about user safety vs security fix delivery.**
+   *Disposition:* **Documented.** Adding a paragraph below to call this out explicitly:
+
+   > User-customized `telegram-reply.sh` scripts (those whose SHA-256 is not in the migrator's prior-shipped set) do *not* receive the agent-id binding fix automatically. They get a `.new` candidate file alongside their original and a `relay-script-modified-locally` degradation event. This is intentional — overwriting user customizations would be a worse failure mode — but it does mean the security fix has opt-in delivery for any agent that has ever been customized. The migrator's same-PR follow-up CI lint (concern #4 above) will help ensure the prior-shipped set captures every released version, minimizing the population that lands on the `.new` path inappropriately.
+
+**Concur-after-fix.** Findings 1, 2, 3 fully addressed in this PR; 4 partially addressed (noise dedup landed; CI lint deferred to same-branch follow-up); 5–7 accepted with documentation. Layer 1 is clear to ship.
+
+---
+
+## Evidence pointers
+
+- Bug-fix evidence: the original incident at topic 50 on 2026-04-27 17:44 UTC produced a `403 Invalid auth token` from a wrong-port server. With Layer 1 in place, the same script invocation against the same wrong port produces `403 { error: "agent_id_mismatch", expected: "<right-agent>" }` — and the wrong agent's server processes only an audit log line, never the message body. Reproducing this end-to-end requires real two-server setup, deferred to Layer 3's `tests/integration/delivery-recovery-cross-port.test.ts`. Layer 1 unit tests cover the equivalent decision points: `tests/unit/auth-agent-id-binding.test.ts` (7 tests), `tests/unit/telegram-reply-port-resolution.test.ts` (5 tests), `tests/unit/whoami-route.test.ts` (5 tests), `tests/unit/migration-relay-script-hash.test.ts` (5 tests), `tests/unit/PostUpdateMigrator-telegramReply.test.ts` (13 tests, updated).
+- Test results: 35 new + 13 updated tests, all passing. Full unit suite: 13554 passing / 7 failing. Of the 7 failures, 6 pre-exist on origin/main (`security.test.ts > zero execSync` from commit 18a6735b's nuke.ts; `agent-registry.test.ts > port allocation` × 2; `ListenerSessionManager.test.ts > starts in dead state`; `pre-push-gate.test.ts` was failing on main and was fixed by this PR). The 7th was a transient race in `middleware-behavioral.test.ts` that re-runs cleanly.
+- TypeScript: `pnpm tsc --noEmit` clean.
+- Spec & convergence: `docs/specs/telegram-delivery-robustness.md` (review-iterations: 3, review-convergence: 2026-04-27T18:35:00Z, approved: true), `docs/specs/reports/telegram-delivery-robustness-convergence.md`.