instar 1.1.2 → 1.1.3

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-20T22:26:32.053Z",
-  "instarVersion": "1.1.2",
+  "generatedAt": "2026-05-21T00:22:35.171Z",
+  "instarVersion": "1.1.3",
   "entryCount": 190,
   "entries": {
     "hook:session-start": {
@@ -752,7 +752,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:setup": {
@@ -760,7 +760,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:add": {
@@ -768,7 +768,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:backup": {
@@ -776,7 +776,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:git": {
@@ -784,7 +784,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:memory": {
@@ -792,7 +792,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:knowledge": {
@@ -800,7 +800,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:semantic": {
@@ -808,7 +808,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:intent": {
@@ -816,7 +816,7 @@
       "type": "cli-command",
       "domain": "intent",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:feedback": {
@@ -824,7 +824,7 @@
       "type": "cli-command",
       "domain": "feedback",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:server": {
@@ -832,7 +832,7 @@
       "type": "cli-command",
       "domain": "server",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:status": {
@@ -840,7 +840,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:user": {
@@ -848,7 +848,7 @@
       "type": "cli-command",
       "domain": "users",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:relationship": {
@@ -856,7 +856,7 @@
       "type": "cli-command",
       "domain": "relationships",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:job": {
@@ -864,7 +864,7 @@
       "type": "cli-command",
       "domain": "scheduling",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:lifeline": {
@@ -872,7 +872,7 @@
       "type": "cli-command",
       "domain": "communication",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:list": {
@@ -880,7 +880,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:autostart": {
@@ -888,7 +888,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:migrate": {
@@ -896,7 +896,7 @@
       "type": "cli-command",
       "domain": "updates",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:machines": {
@@ -904,7 +904,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:whoami": {
@@ -912,7 +912,7 @@
       "type": "cli-command",
       "domain": "identity",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:pair": {
@@ -920,7 +920,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:join": {
@@ -928,7 +928,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:wakeup": {
@@ -936,7 +936,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:leave": {
@@ -944,7 +944,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:doctor": {
@@ -952,7 +952,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:review": {
@@ -960,7 +960,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:nuke": {
@@ -968,7 +968,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "cli:playbook": {
@@ -976,7 +976,7 @@
       "type": "cli-command",
       "domain": "context",
       "sourcePath": "src/cli.ts",
-      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
+      "contentHash": "ef620787cb2d40a51831b00ba7071e67aa0d4cac86027dc3a04635d344608d29",
       "since": "2025-01-01"
     },
     "template:build-stop-hook.sh": {
@@ -1496,7 +1496,7 @@
       "type": "subsystem",
       "domain": "communication",
       "sourcePath": "src/lifeline/TelegramLifeline.ts",
-      "contentHash": "ad363d58349530646209a1ee6b97e0039449c70c6cf61c87d3c590c9e39d25e4",
+      "contentHash": "45cd2b449e34134cae67859e79e378ccc131f481b4d5701faf26913b8a3a26e2",
       "since": "2025-01-01"
     },
     "subsystem:orphan-process-reaper": {

package/upgrades/1.1.3.md

@@ -0,0 +1,124 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**fix(lifeline): close the silent-drop version-skew failure class.**
+
+Five interlocking fixes that together address the 2026-05-19 →
+2026-05-20 b2lead-insights field incident (21h silent Telegram ingress
+drop after a server auto-update from v1.0.13 → v1.1.0 left the
+lifeline on v1.0.13; server's `/internal/telegram-forward` rejected
+the lifeline with HTTP 426 and the lifeline's drop-after-3-failures
+replay policy silently lost user messages).
+
+1. **`rateLimitState.decide` — `versionSkew` bucket bypasses
+   cooldown.** A hard incompatibility cannot be cured by waiting; the
+   per-minute cooldown wedged every restart attempt. The daily cap
+   (3 per 24h) and storm detection remain as backstops.
+
+2. **Replay-loop drop policy is gated on a version-skew episode
+   flag.** When `forwardToServer` raises `ForwardVersionSkewError`,
+   the lifeline sets `versionSkewActive = true` and sends one
+   user-visible Telegram alert ("ingress paused: version skew
+   detected, your messages are not lost"). The replay loop checks
+   the flag BEFORE the `MAX_REPLAY_FAILURES` drop check and re-queues
+   without incrementing the failure counter. Cleared on the next
+   successful forward.
+
+3. **`instar lifeline restart` CLI uses the correct service label.**
+   Was `com.instar.<projectName>.lifeline` — different domain AND
+   different suffix from what `installMacOSLaunchAgent` writes
+   (`ai.instar.<projectName>`). `launchctl kickstart` always failed,
+   silently fell back to pkill.
+
+4. **pkill fallback escalates to SIGKILL; lock-acquire recognizes
+   wedged sleeping processes.** SIGTERM, 3s grace, SIGKILL by name
+   pattern in the CLI. In `acquireLockFile`, 'S' (sleeping) state
+   with lock-write age > 5 min is treated as a wedged lifeline:
+   SIGTERM → 3s poll → SIGKILL → take the lock.
+
+5. **`npm rebuild` for better-sqlite3 uses `--build-from-source` and
+   `--ignore-scripts`.** Two call sites: `ServerSupervisor`
+   preflight rebuild and `NativeModuleHealer.healBetterSqlite3Sync`.
+   Without `--build-from-source`, npm can install a cached prebuilt
+   with the same wrong ABI and exit 0 — producing the "rebuild
+   succeeded but module still fails to load" pattern in the b2lead
+   logs.
+
+Files touched (excluding tests / docs / upgrade notes):
+- `src/lifeline/rateLimitState.ts` — `decide()`
+- `src/lifeline/TelegramLifeline.ts` — instance state,
+  `handleVersionSkew`, `forwardToServer`, `replayQueue`,
+  `acquireLockFile`
+- `src/cli.ts` — `lifelineCmd.command('restart')`
+- `src/lifeline/ServerSupervisor.ts` — preflight rebuild argv
+- `src/memory/NativeModuleHealer.ts` — in-line rebuild argv
+
+## Evidence
+
+**Repro of the original failure** (b2lead-insights, 2026-05-19 evening
+→ 2026-05-20 ~17:50 UTC):
+
+1. Server auto-updated v1.0.13 → v1.1.0.
+2. Lifeline kept running v1.0.13.
+3. User Telegram messages → lifeline forwards to server → server
+   returns HTTP 426 with `{ok: false, upgradeRequired: true,
+   serverVersion: '1.1.0', action: 'restart', reason: 'major-minor-mismatch'}`.
+4. Lifeline catches `ForwardVersionSkewError`, calls
+   `handleVersionSkew` → `initiateRestart('versionSkew', ...)`.
+5. `RestartOrchestrator.maybeRestart` consults `rateLimitState.decide`.
+   `elapsed < WATCHDOG_COOLDOWN_MS` → returns `{allowed: false, reason:
+   'cooldown-active'}`. No restart.
+6. Lifeline returns false from `forwardToServer`. Replay loop
+   increments `replayFailures`. After 3 attempts → drop.
+7. 40+ "server-down" notifications + at least 2 explicitly-logged
+   dropped messages (`tg-6577`, `tg-6580`). No user-visible alert.
+
+**Observed before:** `rateLimitState.ts:112` had no special-case for
+`versionSkew` — the cooldown check fired for all buckets. The replay
+loop at `TelegramLifeline.ts:1394` checked `failures >=
+MAX_REPLAY_FAILURES` unconditionally. The CLI restart command at
+`cli.ts:1639` hardcoded `com.instar.${projectName}.lifeline`.
+`ServerSupervisor.ts:751` and `NativeModuleHealer.ts:397` both ran
+`npm rebuild better-sqlite3` without `--build-from-source`.
+
+**Observed after:**
+- 26 new + extended unit tests (8 new in
+  `tests/unit/lifeline/version-skew-recovery.test.ts`, 1 new in
+  `tests/unit/lifeline/rateLimitState.test.ts`) cover all five paths.
+- Source assertions verify the supervisor rebuild argv includes
+  `--build-from-source` AND `--ignore-scripts`, the healer in-line
+  rebuild includes both flags, the CLI restart command builds
+  `ai.instar.${...}` and never `com.instar.${...}.lifeline`, the
+  pkill fallback contains both `-TERM` and `-KILL`, the
+  `versionSkewActive` flag is set in `handleVersionSkew`, cleared in
+  `forwardToServer` success, checked in `replayQueue` BEFORE the
+  drop branch, and the lock-acquire path recognizes wedged-S.
+
+Spec: `docs/specs/lifeline-version-skew-recovery.md`
+ELI16: `docs/specs/lifeline-version-skew-recovery.eli16.md`
+Side-effects review: `upgrades/side-effects/lifeline-version-skew-recovery.md`
+
+## What to Tell Your User
+
+- **You will never silently lose a message during an auto-update
+  again**: if my server and my Telegram lifeline temporarily get out
+  of sync after an update, I'll send you one clear note that ingress
+  is paused, keep all your messages safely in the queue, and replay
+  them as soon as the lifeline catches up.
+- **Recovery is automatic**: the bug class that needed a manual
+  restart to clear is now self-healing. No operator intervention.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Version-skew cooldown bypass | automatic |
+| Version-skew user alert (one per episode) | automatic |
+| No-drop policy during version-skew episodes | automatic |
+| CLI lifeline restart resolves correct service | automatic via `instar lifeline restart` |
+| Wedged-lifeline lock recovery | automatic |
+| Force-from-source native rebuilds | automatic |

package/upgrades/side-effects/lifeline-version-skew-recovery.md

@@ -0,0 +1,180 @@
+# Side-Effects Review — Lifeline version-skew recovery
+
+**Version / slug:** `lifeline-version-skew-recovery`
+**Date:** `2026-05-20`
+**Author:** Echo (instar developer agent)
+**Trigger:** 2026-05-19 → 2026-05-20 b2lead-insights field incident (21h silent
+Telegram ingress drop after server auto-update from v1.0.13 → v1.1.0;
+lifeline stayed on v1.0.13; HTTP 426 from `/internal/telegram-forward`
+went to 3-attempts-then-drop replay policy; restart attempts blocked by
+cooldown; manual operator recovery required).
+
+## Summary of the change
+
+Five interlocking fixes that together close the silent-drop failure
+class. All independently revertable.
+
+1. **Rate-limit cooldown bypass for `versionSkew` bucket.** A
+   no-op-against-mismatch wait is replaced with allow-but-rate-limit
+   (daily cap still applies). One-line condition change in
+   `decide()`.
+
+2. **Drop policy guards on `versionSkewActive` instance flag.** Three
+   new state operations:
+   - `handleVersionSkew` sets `versionSkewActive = true` and fires
+     one user-visible alert (dedupe via `versionSkewAlertSentAt`).
+   - `forwardToServer` success clears the flag + dedupe timestamp.
+   - `replayQueue` re-queues without incrementing failures while
+     the flag is set.
+
+3. **CLI service label fix.** `com.instar.<name>.lifeline` →
+   `ai.instar.<name>`. Matches the plist label written by
+   `installMacOSLaunchAgent`. Stops the always-fall-back-to-pkill path.
+
+4. **pkill fallback escalates + lock-acquire recognizes wedged-S.**
+   CLI: SIGTERM, 3s grace, SIGKILL by pattern. Lock-acquire: detects
+   sleeping ('S') state with lock-write age > 5 min as a wedged
+   lifeline, sends its own SIGTERM → 3s poll → SIGKILL sequence.
+
+5. **`--build-from-source` + `--ignore-scripts` on every native
+   rebuild.** Two call sites: ServerSupervisor preflight rebuild
+   (line 751) and NativeModuleHealer.healBetterSqlite3Sync
+   (line 397). The Remediator-orchestrated path already had these
+   flags (NativeModuleHealer.healBetterSqlite3FromRemediator).
+
+Files touched (excluding tests / docs):
+- `src/lifeline/rateLimitState.ts` — `decide()` cooldown bypass
+- `src/lifeline/TelegramLifeline.ts` — instance state, `handleVersionSkew`,
+  `forwardToServer`, `replayQueue`, `acquireLockFile`
+- `src/cli.ts` — label fix + pkill escalation
+- `src/lifeline/ServerSupervisor.ts` — rebuild flags
+- `src/memory/NativeModuleHealer.ts` — rebuild flags
+
+## Decision matrix
+
+### Over-block
+
+| Scenario | Outcome |
+|----------|---------|
+| Lifeline at SAME version as server (no skew) | No change — `versionSkewActive` stays false |
+| Lifeline at OLD version, server unchanged (no auto-update) | No change — no 426, no skew |
+| Genuine transient 5xx | Drop-after-3 still fires (versionSkewActive is false) |
+| `ForwardServerBootError` (server starting) | Drop-after-3 still fires — known limitation; this PR doesn't try to also branch on serverBoot. Out of scope. Justified: serverBoot is short-lived (seconds), version skew is steady-state until restart. |
+| Lifeline restart loop after fix | Daily cap (3-per-24h) plus storm detection bound the loop |
+
+No over-block. The new authority only fires when ALL of:
+1. The forward threw `ForwardVersionSkewError`,
+2. The server version in the body differs from the lifeline's,
+3. The body's `upgradeRequired === true`.
+
+That's the same gate that already triggers the restart request, so we
+haven't widened the surface — just made the consequences during the
+window correct.
+
+### Under-block
+
+| Scenario | Outcome |
+|----------|---------|
+| Lifeline version "skews" because of a malformed 426 body | Guarded by existing `body.upgradeRequired !== true` and `serverVersion === this.lifelineVersion` checks — they were already in `handleVersionSkew` |
+| Lifeline tries to forge a skew to bypass cooldown | The 426 must come from the SERVER (loopback addr only on a privileged port); the lifeline cannot self-trigger the body shape |
+| Two version-skew episodes in <24h (daily cap reached) | Falls through to existing `version-skew-daily-cap` denial — observability path remains intact |
+| Stuck-lock detection: live healthy lifeline misidentified as wedged | Requires lock-age > 5 min AND 'S' state — a healthy lifeline writes the lock, immediately starts polling Telegram (lots of 'R' time), and answers heartbeats. Misidentification window is narrow but possible during long Telegram long-poll waits. Acceptable: false positive triggers SIGTERM → 3s grace → SIGKILL of a healthy lifeline → launchd respawns it within seconds. Worst case: ~5s downtime + a fresh boot. Far better than the 21h+ silent drop the current code permits. |
+| Forced rebuild with `--build-from-source` fails because node-gyp toolchain absent | Already-existing failure path: spawnSync returns non-zero, healer logs error, falls back to existing escalation. No new silent failure. |
+
+### Level of abstraction fit
+
+- Rate-limit bypass — at the decision-point that already knows about
+  buckets. Right layer.
+- Drop policy — at the replay loop that already has the failure-counter
+  state. Right layer. Could have lived in `forwardToServer` instead,
+  but the queue is what owns "should this message be dropped" — the
+  forward path only owns "did this single attempt succeed".
+- CLI label — at the kickstart callsite. One source of truth.
+- pkill escalation — at the CLI fallback. The CLI is the place where
+  "user typed `instar lifeline restart`" gets translated to a system
+  action.
+- Lock-acquire — at the lock-acquire function. The detector and the
+  recovery primitive are both bounded mechanics in the same scope.
+- Rebuild flags — at the rebuild callsites. No new abstraction.
+
+No over-engineering. Each change is at the layer that already owns
+the concern.
+
+### Signal-vs-authority compliance
+
+- `rateLimitState.decide` — returns signal. No authority change.
+- `versionSkewActive` flag — pure state signal. Replay loop is the
+  authority that decides re-queue vs drop.
+- `handleVersionSkew` — already had authority over "request a restart".
+  Now also: sets the flag and sends an alert. Both are bounded
+  mechanics with clear preconditions, not judgmental gates.
+- CLI label — mechanical change.
+- pkill escalation — bounded recovery (fixed 3s grace, single SIGKILL).
+- Lock-acquire stuck-S — bounded recovery (fixed 5min threshold for
+  age, 3s SIGTERM grace, single SIGKILL).
+- Rebuild flags — mechanical change.
+
+Compliant. No new judgmental gates; new authorities are bounded
+recovery primitives.
+
+### Interactions with adjacent systems
+
+| System | Interaction | Risk |
+|--------|-------------|------|
+| `MessageQueue` | Replay loop re-queues messages during skew (same enqueue path used for transient failures) | None — queue persistence semantics unchanged |
+| `notifyMessageDropped` | NOT called during version-skew episodes (drop is suppressed) | Strictly improves — these messages will deliver |
+| `DegradationReporter` | Still fires for non-skew drops; version-skew episode itself emits a degradation via the existing path | None |
+| `RestartOrchestrator` | Receives a `versionSkew` request that's now more likely to be granted (cooldown bypass) | Storm detection + daily cap remain as backstops |
+| `ServerSupervisor.preflightSelfHeal` | Rebuild flag change is a strict improvement | None |
+| Remediator (Tier 1+) | Not yet shipped; in-line healer is the steady-state path. When Remediator ships, its rebuild already used `--build-from-source` — no conflict | None |
+| `NativeModuleHealer.invokeFromRemediator` | Unchanged (already had the flag) | None |
+| `LifelineHealthWatchdog` | Tracks `consecutiveForwardFailures`; this PR clears it on success (existing behavior). No change to the watchdog's trip conditions | None |
+| `WatchdogTriggers.versionSkew` | The flag-set + alert-send happens BEFORE `initiateRestart`. If the restart is rate-limited, the alert still fires — good (user knows ingress is paused even while the lifeline is being patient about restarts) | None |
+| `acquireLockFile` callers | The added SIGTERM-then-SIGKILL path runs in the boot-startup window. New lifelines that find a wedged old one will spend up to 3s waiting for graceful exit. Acceptable | None |
+| Existing tests | All 18 `rateLimitState.test.ts` + 14 `lifeline-shadow-install-self-heal.test.ts` + 9 `NativeModuleHealer.test.ts` tests pass unchanged | Verified |
+
+### Rollback cost
+
+- Each fix is independently revertable.
+- No persistent state schema changes; the new lifeline instance
+  fields (`versionSkewActive`, `versionSkewAlertSentAt`) are not
+  serialized to disk.
+- No migration entry; existing in-the-wild agents pick up the fix on
+  their next `npx instar` update like any other patch.
+- Reverting the rebuild flag returns to the pre-existing flaky
+  rebuild behavior — agents that had drifted to "rebuild succeeded
+  but still fails" on the old code path continue exactly as they
+  did.
+
+## Acceptance criteria (test-mapped)
+
+1. `tests/unit/lifeline/rateLimitState.test.ts > versionSkew bucket
+   BYPASSES the cooldown` — asserts the new bypass.
+2. `tests/unit/lifeline/version-skew-recovery.test.ts > CLI service
+   label` — asserts `ai.instar.${...}` is in source and
+   `com.instar.${...}.lifeline` is gone.
+3. `tests/unit/lifeline/version-skew-recovery.test.ts > pkill
+   fallback escalates to SIGKILL` — asserts both signal calls
+   present in the restart command source.
+4. `tests/unit/lifeline/version-skew-recovery.test.ts >
+   ServerSupervisor preflight rebuild passes --build-from-source` —
+   asserts the rebuild argv on the supervisor side.
+5. `tests/unit/lifeline/version-skew-recovery.test.ts >
+   NativeModuleHealer in-line rebuild passes --build-from-source` —
+   asserts EVERY rebuild call in the healer source has the flag.
+6. `tests/unit/lifeline/version-skew-recovery.test.ts > lifeline
+   source guards drop with versionSkewActive` — asserts the source
+   order (skew bypass before drop check).
+7. `tests/unit/lifeline/version-skew-recovery.test.ts >
+   handleVersionSkew sets the active flag + alert dedupe`.
+8. `tests/unit/lifeline/version-skew-recovery.test.ts >
+   forwardToServer success clears the version-skew episode flag`.
+9. `tests/unit/lifeline/version-skew-recovery.test.ts > lock-acquire
+   treats sleeping (S) state > 5 min as recoverable`.
+
+## Forward note
+
+If the auto-update flow eventually grows a "tell the lifeline to
+restart" step, the failure class this PR addresses becomes
+impossible-by-construction. Until then, this is the steady-state
+recovery for the window between server-update and lifeline-restart.